방금 작성한 새로운 코드를 통해 클래스와 메소드에 NDoc sytle 주석을 추가합니다. 나는 꽤 좋은 MSDN 스타일의 문서를 생성하기를 기대하고있다.XML 주석을 사용하여 C# 코드를 문서화하는 모범 사례는 무엇입니까?
일반적으로 클래스 및 메서드에 대한 의견을 쓸 때 좋은 지침은 무엇입니까? NDoc 의견은 무엇을 말해야합니까? 그들은 무엇을 말하지 않아야합니까?
.NET 프레임 워크 주석이 말하는 것을 보았지만 느린 속도가되었습니다. 만약 내가 자신을 인도하기위한 좋은 규칙을 가질 수 있다면, 나는 내 문서를 훨씬 빨리 끝낼 수있다.
을 수행해야합니다
이 전혀 존재 이유를 메서드 나 속성은 무엇을 설명하고, 평균 자명하지 않은 모든 도메인 개념을 설명 코드의 소비자.
목록 당신의 매개 변수에 대한 모든 전제 조건 (특정 범위 내에 있어야 등을 null 일 수 없습니다)
목록 호출자가 반환 값을 처리하는 방법에 영향을 미칠 수있는 사후.
메서드가 throw 할 수있는 예외 (어떤 경우)를 나열하십시오.
비슷한 방법이있는 경우 그 차이점을 설명하십시오.
예기치 않은 문제 (예 : 글로벌 상태 수정)에주의를 환기시킵니다.
부작용이있을 경우이를 나열하십시오.
가치를 추가하지 않는 의견으로 끝나면 단지 낭비입니다. 예를
/// <summary>
/// Gets manager approval for an action
/// </summary>
/// <param name="action">An action object to get approval for</param>
public void GetManagerApprovalFor(Action action)
를 들어
... 당신이 유지하는 절대적 가치와 방금 추가 한 더 많은 코드를 추가하지 않습니다.
너무 많은 코드가 이러한 불필요한 주석으로 흩어져 있습니다.
예, 의견이 가치가 없음을 이해합니다. 그것이 내가 가치를 제공하는 의견에 대한 지침을 찾는 이유입니다. –
나는 그것이 가난한 문서화의 한 예라고 생각합니다. 사용하지 말아야 할 곳의 예가 아닙니다. 공개 메소드에는 예상 예외, 전제 조건 등과 같은 추가 문서가 있어야합니다. 예를 들어 action이 null 일 때 해당 메소드는 어떤 작업을 수행합니까? –
나는 superfulous 코멘트의 주제에 동의하지만, superfulous 문서는 다른 문제입니다. 어떤 경우에는 문서에 추가 할 것이 아무것도없고 xml 문서 문자열은 메서드 이름의 메아리 일 뿐이지 만 여전히 그 docsctring을 추가합니다 - 부분적으로는 메서드가 단순한 것처럼 보이기 때문에 (오히려 누군가 그 방법을 문서화하는 것을 괴롭히지 않는 것보다). – Justin
속성의 경우 해당 속성이 읽기 전용인지, 쓰기 전용인지 또는 읽기 전용인지 여부를 나타내는 주석이 있어야합니다. 모든 MS 공식 문서를 보면 등록 정보 문서 주석은 항상 "가져 오기 ...", "가져 오기 또는 설정 ..."으로 시작하고 (보통 드물게 쓰기 전용 속성은 사용하지 마십시오) "설정 ..."
좋아요! 방법과 수업에 대한 아이디어가 있습니까? –
모든 정직한면에서 의사의 의견을 진지하게 받아들이는 유일한 회사는 Microsoft입니다. 나는 자신의 의견을 검색하고 어떻게 수행하는지에 대한 느낌을 얻습니다. 그들은 의견을 형식화하는 방법과 그들이 말해야하는 것에 대한 기준을 분명히 가지고 있습니다. MS는 또한 메서드가 throw하는 예외를 나타내는 훌륭한 작업을 수행합니다. 슬프게도, 의사 주석은 C# 언어 IMO의 사소한 문제를 해결하기위한 밴드 원조로 사용됩니다. (주석이나 컴파일러 오류로 인해 속성이 읽기 전용인지 알아내는 등) –
나는 의사의 의견을 진지하게 받아들입니다. 나는 마이크로 소프트에서 일하지 않는다. GhostDoc과 Sandcastle/Sandcastle Help File Builder 사이의 훌륭한 문서 주석 사이에는 핵심 라이브러리에 개발자가 참조 할 수있는 웹 사이트가 있습니다. 필자는 ** 간결한 문서를 읽는 대신 코드를 단계별로 실행하여 메서드/속성 사용법을 이해하는 것을 정말로 싫어합니다. –
MSDN page에 명시된 바와 같이 XML 문서 주석을 사용하여 설명서를 자동으로 생성하므로 API를 작성하고 코드 및 설명서에서 두 번 작업하지 않아도됩니다. sync - 코드를 변경할 때마다 적절한 주석을 수정하고 문서를 재생성합니다.
/doc으로 컴파일하면 컴파일러에서 소스 코드의 모든 XML 태그를 검색하고 XML 문서 파일을 만든 다음 Sandcastle과 같은 도구를 사용하여 전체 문서를 생성합니다.
필자는 XML 문서의 장점과 방법을 배웠습니다. 사람들이 실제로이 주석에서 유용하다고 생각하는 것에 대해 약간의 도움이 필요합니다. –
@Esteban Araya 내가 말했듯이, 문서화중인 실제 코드와의 근접성 덕분에 다른 앱으로 전환하거나 수정할 적절한 장소를 검색 할 필요없이 그 자리에서 변경 사항을 문서화 할 수 있습니다. – luvieere
의견에 대한 한 가지는 업데이트하는 것입니다. 함수를 변경하는 사람이 너무 많으면 변경 사항을 반영하기 위해 주석을 변경하지 마십시오. API 문서를 작성하는 데 사용되는 의견에
참. 우리는 과거에 표준 코드 검토 체크리스트의 일부로이를 수정했습니다. –
StyleCop 코드 및 주석 스타일에 대한 힌트를 제공한다. 제안 사항은 MSDN 설명서 스타일과 일치합니다.
주석의 내용은 예상되는 동작의 종류에 대한 충분한 정보를 코드 사용자에게 제공해야합니다. 또한 사용자가 가질 수있는 잠재적 인 질문에 대답해야합니다. 코드에 대해 아무 것도 모르는 사람으로 코드를 사용하거나 다른 사람에게 그렇게하도록 요청하십시오.
StyleCop은 메서드에서 매개 변수를 추가/제거하고 '
또 다른 옵션 : Resharper가 UI에서이를 수행합니다. –
나는 < 요약 >을 작성하여 해당 기능을 호출하거나 (또는 해당 클래스를 인스턴스화하는 경우) 알고 싶었던 정보를 포함합니다.
< 비고 >은 디버깅이나 기능 향상을 위해 필요한 정보를 포함하도록 주석을 씁니다. 참고 : 좋은 인라인 코멘트의 필요성을 대체하지는 않습니다. 그러나 때로는 함수/클래스의 내부 동작에 대한 일반적인 개요가 매우 유용합니다.
유효한 XML이 무엇인지 잊지 마세요. 예 :
/// <Summary>
/// Triggers an event if number of users > 1000
/// </Summary>
(오류 : 잘못된 XML).
+1. 나는 사전 조건 팁을 정말로 좋아한다. –
+1. 필자는 외부 인터페이스 (doxygen, NDoc 등)를 생성 할 때 문서에 대한 주안점이 공개 인터페이스 용이어야한다고 생각합니다. 고객은 수업의 구석 구석을 알아야 할 필요가 없습니다. 구현 세부 정보는이 형식으로 문서화 할 필요가 없습니다. 주된 초점은 공용 인터페이스, 사용 방법, 사전/사후 조건 및 Jeff가 지적한 기타 사항에 있어야합니다. – stinky472
공용 인터페이스에 대해 일관되고 효과적인 문서가 있어야하지만, 기존 코드 기반을 업데이트, 수정 또는 다시 작성하는 작업이 포함 된 경우 개인 및 보호 된 항목의 문서화가 매우 유용합니다. – EoRaptor013