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


10

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

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가이 표준을 채택한 이유에 대한 정보가 있습니까?

답변:


3

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

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

/// <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 초를 소비하면서 코드의 추가 독자에 대한 소비를 줄일 수 있다면 그렇게하십시오.


1
메소드를 호출하고 있으며 메소드가 무엇인지 알고 싶지 않습니다!?
jk.

1
@ jk : 그는 이미 이미 그렇게했음을 암시합니다. 실패한 경우에만 반환 값에 '포커스'를 원합니다. 마지막 단락에 +1, 그것은 본질적으로 내가 느끼는 방식입니다. 심지어 경우에 문서 내 예에서와 같이 명백한 사실을 언급, 그것은 자신의 기대에 독자를 안심. 주석이 제대로 관리되면 msdn 설명서 에서처럼 "이 방법은 올바르게 고려되었으며 여기에 언급 된 것 이상을 수행하지 않습니다"라고 표시됩니다.
Steven Jeuris

2

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

MSDN 링크 : <summary>.<returns>


링크 주셔서 감사합니다. 그러나 summary상태에 대한 msdn 문서 는 '방법이하는 일'을 설명하지 않습니다. msdn 상태와 공식 구성의 차이점을 명확히하기 위해 답변을 업데이트 할 때까지 투표를했습니다. ; p
Steven Jeuris

2
MSDN이 그것에 대해 아무 말이나하지 않더라도 실제로 이것은 좋은 지침입니다. 예를 들어, 전체 요약을 반복 할 필요는 없습니다 true. "조건자가 일치하면 리턴 합니다 "라고 말할 수 있습니다 . 누군가가 일치하는 것이 무엇인지 알아야하는 경우 나머지 문서를 읽을 수 있습니다.
Blrfl

@Blrfl : 나는 지침이 틀렸다고 말하는 것이 아닙니다. 나는 소스를 참조하는 것이 잘못되었다고 말하고 있습니다. 따라서 하향 투표. 이 답변이 수정 된 것을보고 싶습니다.
Steven Jeuris

@StevenJeuris : MSDN 설명서에 대한 링크는 추가 정보 일뿐입니다. "당신이있을 때 MSDN은 말을하지 않습니다 <summary>그리고는 <returns>이렇게". Blrfl이 말했듯이 이것은 사용하거나 사용하지 않을 수있는 지침 일뿐입니다.
Jake Berger

1
@StevenJeuris : 작성된 방식으로 인해 누군가 MSDN에서 온 것으로 추론 할 수 있습니다.
Jake Berger

1

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

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

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

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


1

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

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

그렇습니다, 나는 언급 한 요점과 연결할 수 있으며 그 정도를 따릅니다. 문제는 꽤 주관적인 규칙이므로 Microsoft가 항상 returns대신 추가하기로 선택한 이유 일 수 있습니다 . 또한 부울 리턴 값에 대해 항상 동일한 공식을 사용합니다 (예 : "true if ...; 그렇지 않으면 false "). 나는 그들이 그것을 위해 협약을 지정했는지 궁금합니다.
Steven Jeuris

0

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

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

된다

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


실제로, 그렇게 작성하면 "Determines whether ..." 로 시작하는 Microsoft의 표준 방식의 이점을 알게되었습니다 . 결과가 무엇인지 말하기 전에 먼저 수행중인 작업을 설명하기 때문에 더 읽기 쉽습니다. 그것은 간접적으로 한 걸음 줄입니다. returnsMicrosoft가 너무 길다는 데 동의합니다 . 그것이 무엇인가를해야한다면, 그것은 참이 그것이 일치한다는 것을 의미하고, 그렇지 않다는 것을 단순히 안심시키는 것입니다.
Steven Jeuris
당사 사이트를 사용함과 동시에 당사의 쿠키 정책개인정보 보호정책을 읽고 이해하였음을 인정하는 것으로 간주합니다.
Licensed under cc by-sa 3.0 with attribution required.