XML 주석에 제공 할 정보는 무엇입니까?

Question

메소드를 작성하고 주석을 달려면 동일한 정보를 요약 태그에 씁니다.

예 : 마지막으로

/// <summary> 
/// Get a <typeparamref name="Customer">customer</typeparamref> by its ID 
/// </summary> 
/// <param name="id">customer id</param> 
/// <returns>a <typeparamref name="Customer">customer</typeparamref></returns> 
private Customer GetCustomerById(string id) 
{ 
    ... 
} 

, 그것은이 정말 유용? 어떤 정보가 어떤 태그를 제공합니까?

Answer 1

DRY를 고려하십시오 (반복하지 마십시오). param 항목은 매개 변수를 설명하고 returns 항목은 반환되는 항목을 설명합니다. 요약은 메소드가하는 일에 대한 개요를 제공하고 다른 항목의 정보는 반복하지 않아야합니다.

실제 설명서가 누락되었습니다. "문자열 ID"는 ID가있는 문자열입니다. 즉, 자체 문서화입니다. 그러나이 방법을 어떻게 호출해야합니까? 유효한 사용자 ID는 무엇입니까? null 또는 빈 문자열을 전달하면 어떻게됩니까? 다음 매개 변수 세부의 이러한 종류의 복제 내 추가 기능 (Atomineer Pro Documentation)와 같은 도구를 사용하는 경우

/// <summary> Gets information on a customer </summary> 
/// 
/// <param name='id'> A customer identifier in the form of a GUID string. 
/// e.g. "{D8C447DD-0E7F-4C8B-A3E5-2C6E160D297B}". 
/// Braces around the GUID are optional. 
/// This parameter must be a valid Guid. </param> 
/// 
/// <returns> A Customer record describing the given customer, or 
/// null if the Customer is not found</returns> 

: 등

는

다음 방법을 사용하는 어떤 일을위한 방법의 설명서가 포함되어 가상의 예입니다 클래스를 중심으로하는 것은 쉽지 않으므로 메서드를 문서화하는 데 시간이 많이 걸릴 필요는 없습니다.

Answer 2

또 다른 질문에 대한 답변은 또한 당신에 응답 할 것이다 :

정말 유용한 문서를 제공하고 있습니까?

필요하고 유용하다고 생각되는 것을 제공하십시오. 이 정보는 .NET 클래스 및 멤버에서 볼 수있는 것처럼 Visual Studio의 코드 소비자에게 IntelliSense 툴팁으로 나타납니다.

Answer 3

Xml 설명서는 라이브러리를 개발할 때 매우 유용합니다. 이러한 XML 주석에 대해 도움말 파일이 자동으로 생성 될 수 있습니다. 도움말 파일 생성에 대한 자세한 내용은 this을 참조하십시오. Xml documentation 태그에 대한 자세한 내용은 MSDN을 확인하십시오.

Answer 4

때로는 메서드 나 속성 이름이 설명이 필요하지만 항상 그런 것은 아닙니다. 귀하의 모범을 보여주는 행사. 제공된 ID가 존재하지 않으면 어떻게되는지 정보를 제공해야합니다. 귀하의 메서드가 예외를 throw합니까 (그렇다면 어떤 예외가 될 것인가) 아니면 그냥 null을 반환하거나 일종의 일반적인 Customer.Empty 값을 반환합니까? 때로는 일부 코드 샘플을 제공 할 수도 있습니다.

어쨌든 항상 코드 문서를 제공하는 것이 좋습니다.

Answer 5

많은 경우에 나는 반환 요소를 완전히 잘라내는 것이 가장 좋습니다. 당신의 모범이 이것의 위대한 모범 인 것처럼 보입니다. 고맙게도, VStudio는 이것을 경고와 함께 나쁜 주석으로 표시하지 않습니다. 내가 이것을하는 이유는 80 % +의 경우에, 나의 문서는 기본적으로 리턴 타입이 무엇인지 이미 설명하고 있기 때문이다. 또는 함수의 이름이 너무 뻔뻔 스럽기 때문에 쓸모없는 시간 낭비와 에너지 낭비이다. 내 견적, 이것을 포함하고, 그것은 종종 DRY의 위반으로 연결됩니다.

귀하의 예는 이것의 완벽한 예입니다.

Customer GetCustomerById(string id) 

int id 인 경우이 함수는 주석이 필요하지 않을 수도 있습니다. 문자열을 사용하면 명확하지 않으며 명확한 설명을 사용할 수 있습니다. 그러나 어느 경우 든 반환 유형에 XML 주석을 제공하는 것은 낭비처럼 보입니다. 이것이 주관적인 질문이라는 점을 명심하십시오. 어떤 사람들은 반환 형식 주석을 항상 포함하도록 완성을 좋아할 수도 있습니다. VStudio의 경고 시스템을 시작으로 이것이 필요하지 않다니 다행입니다.