메소드 주석에 요약과 리턴 설명이 너무 비슷할 때 포함시켜야합니까?

나는 올바르게 문서화 된 코드를지지하는 사람이며 가능한 단점을 잘 알고 있습니다 . 그것은이 질문의 범위를 벗어납니다.

Visual Studio에서 IntelliSense를 얼마나 좋아하는지 고려하여 모든 공개 멤버에 대해 XML 주석 을 추가하는 규칙을 따르고 싶습니다.

그러나 중복성에는 한 가지 형태가 있는데, 나와 같은 과도한 논평자도 귀찮게합니다. 예를 들어 List.Exists ()를 사용하십시오 .

/// <summary>
///     Determines whether the List<T> contains elements
///     that match the conditions defined by the specified predicate.
/// </summary>
/// <returns>
///     true if the List<T> contains one or more elements that match the
///     conditions defined by the specified predicate; otherwise, false.
/// </returns>
public bool Exists( Predicate<T> match )
{
    ...
}

Summary그리고 returns기본적으로 같은 일을 말하고있다. 필자는 종종 returns관점 에서 요약을 작성 하여 returns문서를 완전히 삭제 합니다.

List에 지정된 조건 자에 의해 정의 된 조건과 일치하는 요소가 포함되어 있으면 true를, 그렇지 않으면 false를 반환합니다.

또한 반환 문서는 IntelliSense에 표시되지 않으므로에 즉시 관련 정보를 작성하십시오 summary.

1. 왜 returns별도로 문서를 작성해야 summary합니까?
2. Microsoft가이 표준을 채택한 이유에 대한 정보가 있습니까?

서로를 유추 할 수는 있지만이 두 섹션은 코드를 검토 / 사용할 때 사람이 관심이있는 부분에 집중하는 데 도움이 되므로 별도의 상태로 유지됩니다 .

당신의 모범을 보이면, 나는 오히려 다음과 같이 쓸 것입니다.

/// <summary>
/// Determines whether the List<T> contains elements that match the conditions
/// defined by the specified predicate.
/// </summary>
/// <returns>
/// A value indicating whether at least one element matched the predicate.
/// </returns>
public bool Exists(Predicate<T> match)
{
    ...
}

• 이 코드를 검토하고 있는데 그 방법이 무엇인지 알고 싶다면 요약을 읽습니다. 그게 전부입니다.

• 자, 내가 당신의 방법을 사용하고 있다고 가정 해 봅시다. 이제 메서드의 기능을 알고 싶지 않지만 반환 값에 대해 더 알고 싶습니다. 여기 <returns/>섹션이 도움이되며 요약을 읽을 필요가 없습니다.

다시이 예에서는에서 요약을 유추하고 요약에서 <returns/>예상 반환 값을 유추 할 수 있습니다 . 그러나 극단적으로 동일한 주장을 취하면 이 경우에는 메소드를 전혀 문서화 할 필요가 없습니다 . 단일 인수로 내부 List<T>에 넣은 메소드의 이름 Predicate<T> match은 매우 명시 적입니다.

기억 소스 코드를 한 번 작성하지만, 시간을 많이 읽습니다 . XML 문서에서 추가 문장을 작성하는 데 10 초를 소비하면서 코드의 추가 독자에 대한 소비를 줄일 수 있다면 그렇게하십시오.

내 사용은 :
<summary>설명 방법은 무엇 합니다 (얻을 <returns>). 반환 값을
<returns> 기술합니다 .

MSDN 링크 : <summary>.<returns>

요약과 별도로 반품을 문서화해야하는 이유는 무엇입니까?

요약 부분이 실제로 길고 설명 적이라면 끝에 별도의 간단한 반품 부분을 갖는 것이 유용 할 수 있습니다.

나는 보통 <summary>내 코드로 그 부분을 쓰고 "Returns _ " 라고 말한 방식으로 표현합니다 .

나는 메소드 이름과 매개 변수 (및 그 이름)에서 명확하지 않은 호출자가 알아야한다는 언급을했습니다. 그러나 메서드 이름과 매개 변수를 사용하면 주석이 매우 짧을 수 있습니다.

나는 최근에 같은 철학적 질문으로 찢어졌지만 여전히 좋은 해결책이 무엇인지 잘 모르겠습니다. 그러나 지금까지 이것은 내 접근 방식이었습니다 ...

• 메소드 문서는 외부 호출자가 알아야 할 내용 만 설명합니다. 이 작업이 내부적으로 수행되는 방식에 대해서는 다루지 않지만 a) 호출자가이 메소드를 호출하려는 이유 b) 메소드 호출의 예상 결과는 무엇인지 언급합니다. 메소드의 작동 방식을 문서화해야 할 경우 코드 본문에 넣습니다.
• 방법에 복잡성이 충분하면 일반적인 설명과 별도의 [반품] 섹션이 정당한 것으로 보입니다. 독자가 전체 설명을 읽고 리턴 값을 해석하는 방법을 추론하지 않기를 바랍니다.
• 이 방법이 너무 간단하여 "이 방법은 사람의 주소를 반환합니다"와 같은 것을 말하는 것이 가장 좋은 방법이라면 추가는 DRY 원칙에 어긋나는 것처럼 [반품] 섹션을 건너 뜁니다. 그것의 큰 옹호자. 한 줄짜리 액세서 메소드가이 범주에 속하는 것 같습니다.

요약은 유용 할 수있는만큼 설명 적이어야합니다. 매개 변수와 반환 값에 대한 설명은 짧고 달콤해야합니다. 한 단어와 다섯 단어 중에서 선택할 수 있으면 하나를 사용하십시오. 예를 강화하십시오.

지정된 술어에 의해 정의 된 조건과 일치하는 하나 이상의 요소가 List에 포함되어 있으면 true이고; 그렇지 않으면 거짓입니다.

된다

List의 요소가 술어와 일치하면 true입니다. 그렇지 않으면 거짓.