C# 프로그래밍을 위한 XML 주석 달기 팁 [닫기]
https://stackoverflow.com/questions/355957
-
21-08-2019 - |
italiano
english
français
española
中国
日本の
العربية
Deutsch
한국어
Português
Russian문제
좋은 아침, 오후, 저녁 또는 밤(시간대에 따라 다름).
이것은 C# 내의 XML 주석 처리에 대한 일반적인 질문입니다.나는 내 프로그램에 대해 주석을 달는 데 그다지 열중한 적이 없으며 항상 장황한 변수/속성/메서드 이름 지정자였으며 코드 자체가 말하도록 놔두었습니다.상당히 혼란스러운 내용을 코딩하는 경우에는 댓글을 작성하지만 대부분의 경우 댓글을 많이 작성하지는 않습니다.
나는 .NET, Sandcastle의 XML 주석과 codeplex의 도움말 파일 빌더에 대해 읽고 있었는데, 이를 통해 내 코드를 문서화하고 내 코드를 파헤쳐야 하는 사람들을 위해 훌륭하고 유용한 문서를 생성하고 싶은 길을 걷게 되었습니다. 내가 더 이상 여기에 없을 때 코드를 입력하세요.
내 질문은 표준과 규칙에 관한 것입니다."좋은" XML 주석 작성에 대한 가이드가 있습니까?모든 변수와 속성에 주석을 달아야 합니까?모든 방법?나는 기본적으로 다른 프로그래머들이 내 코드 작업을 하게 될 때 내 이름을 욕하지 않도록 sandcastle을 통해 좋은 문서로 컴파일될 좋은 주석을 작성하는 방법에 대한 팁을 찾고 있습니다.
조언과 제안에 미리 감사드립니다, Scott Vercuski
해결책
개인적으로 우리는 모든 공개 및 보호 메서드에 XML 주석이 있는지 확인합니다.또한 최종 사용자 도움말 문서뿐만 아니라 Intellisense도 제공합니다.과거에는 비공개 범위 선언에도 이를 포함시켰지만 메서드가 짧고 정확하다면 100% 필요하다고 생각하지 않습니다.
XML 주석 달기 작업을 더 쉽게 만들어주는 도구가 있다는 것을 잊지 마세요.
- GhostDoc - 댓글 상속 및 템플릿 추가 기능.
- Sandcastle 도움말 파일 빌더 - GUI를 통해 Sandcastle 프로젝트를 편집하고, 명령줄에서 실행할 수 있으며(빌드 자동화용), 코드에서 파생되지 않은 도움말 항목에 대한 MAML을 편집할 수 있습니다.(1.8.0.0 알파 버전은 매우 안정적이고 많이 개선되었습니다.1.7.0.0 이상으로 약 한 달 동안 사용해 왔습니다.)
다른 팁
의견은 종종 구식입니다. 이것은 항상 문제였습니다. 내 경험의 규칙 : 의견을 업데이트하기 위해 더 많은 노력을 기울여야할수록, 그 의견은 더 빨리 쓸모 없게됩니다.
XML 의견은 API 개발에 좋습니다. 그들은 Intellisens와 잘 작동하며 곧 HTML 도움말 문서를 생성 할 수 있습니다.
그러나 이것은 무료가 아닙니다. 유지하는 것은 어려울 것입니다 (사소한 예를 살펴보십시오. 내가 의미하는 바를 이해할 것입니다). 그래서 그들은 매우 빠르게 구식이 될 것입니다. 결과적으로, XML 댓글 검토 검토는 코드 검토에 필수 점검으로 추가되어야합니다. 이 점검은 파일이 업데이트 될 때마다 수행해야합니다.
글쎄, 유지 비용이 많이 들기 때문에 많은 비 개인 기호 (비 API 개발에서)가 1 또는 2 클래스 만 사용되기 때문에,이 상징은 종종 자기 설명이기 때문에 나는 그 말을하는 규칙을 결코 시행하지 않을 것입니다. 모든 비 개인 기호는 XML에 주석해야합니다. 이것은 과잉과 상호 생산 일 것입니다. 당신이 얻을 것은 내가 많은 장소에서 본 것입니다. 거의 빈 XML 댓글은 Symbole 이름에 아무것도 추가하지 않습니다. 그리고 조금만 읽기 쉬운 코드 ...
나는 그렇게 생각합니다 아주, 아주 정상 (비 API) 코드의 주석에 대한 중요한 가이드 라인은 그들이 어떻게 쓰여야하는지 그러나 거의 그들이 포함해야 할 것. 많은 개발자들이 여전히 모릅니다 무엇 쓰기. 예제와 함께 댓글을 달아야 할 내용에 대한 설명은 "모든 비 민간 심볼에 XML 주석을 사용하십시오."
나는 공개 수업과 해당 수업의 공개/보호 회원을 문서화합니다.
개인 또는 내부 회원 또는 내부 수업을 문서화하지 않습니다. 따라서 변수는 비공개이기 때문에 (필드를 의미한다고 생각합니다).
목표는 소스 코드에 대한 준비가되지 않은 개발자를위한 문서를 작성하는 것입니다.
사용이 명백하지 않은 곳에있는 몇 가지 예를 두려고 노력하십시오.
나는 방법 변수에 대해서는 거의 언급하지 않으며 (일반적으로 속성으로 덮여 있거나, 자동 구현 속성을 사용하는 경우에 존재하지 않기 때문에) 필드는 거의 없습니다.
일반적으로 나는 모든 공개/보호 된 회원에게 의미있는 의견을 추가하려고 노력합니다. 이는 건축 중에 XML 댓글을 켜면 누락 된 의견에 대한 자동 경고를 받기 때문에 편리합니다. 복잡성에 따라 모든 세부 사항을 작성하지 않을 수 있습니다. 즉, 모든 매개 변수가 무엇인지 100% 명백하다면 가지다 해야 할 일 (즉, 특별한 논리가없고 변수를 해석하는 논리적 인 방법은 하나뿐입니다). ~할 것 같다 게으르고 매개 변수에 대한 의견을 추가하지 마십시오.
그러나 나는 확실히 어떤 방법, 유형, 속성 등이 나타내는/do를 설명하려고 노력합니다.
우리는 라이브러리에 공개 방법/속성/등을 문서화합니다. 빌드 프로세스의 일환으로 NDOC를 사용하여 MSDN 유사 웹 참조를 만듭니다. 빠른 참조 및 조회에 매우 도움이되었습니다.
또한 Intellisense, 특히 새로운 팀원들에게 또는 원래 작가가 사라질 때와 마찬가지로, 특히 새로운 팀원들에게도 좋습니다.
나는 일반적으로 코드가 자기 설명이어야한다는 데 동의합니다. 나에게 XML Documention은 소스가 열려 있지 않으면 참조와 조회에 관한 것입니다.
개인적으로 내 의견은 의견을 피하는 것입니다. 댓글은 위험합니다. 업계에서는 항상 코드를 업데이트하기 때문에 (비즈니스 및 요구 사항이 항상 바뀌기 때문에), 우리는 거의 다르지 않습니다. 이것은 프로그래머를 오도 할 수 있습니다.
