XML 문서 주석에 무엇이 포함되어야합니까?

특히 클래스 멤버에 대한 XML 주석과 관련하여 코드를 더 잘 설명하려고 노력하고 있지만 종종 바보 같은 느낌을줍니다.

이벤트 처리기의 경우 명명 규칙과 매개 변수가 표준이며 명확합니다.

/// <summary>
/// Handler for myCollection's CollectionChanged Event.
/// </summary>
/// <param name="sender">Event Sender</param>
/// <param name="e">Event Arguments</param>
private void myCollection_CollectionChanged(object sender, NotifyCollectionChangedEventArgs e)
{
    // actual code here...
}

또한 요약이 중복되도록 명확하게 명명 된 간단한 속성 (IMO)을 자주 사용합니다.

/// <summary>
/// Indicates if an item is selected.
/// </summary>
public bool ItemIsSelected
{ get { return (SelectedItem != null); } }

그러한 의견이 선언 자체가 아직 전달하지 않은 정보를 추가하지 않는 것 같습니다. 일반적인 지혜는 코드를 반복하는 주석이 기록되지 않은 것이 가장 좋습니다.

분명히 XML 문서는 일반적인 인라인 코드 주석 이상의 의미를 가지며, 100 % 적용 범위를 갖습니다. 그러한 경우에 무엇을 써야 합니까? 이러한 예가 문제가 없다면, 지금 감사하지 않을만한 가치가있는 것은 무엇입니까?

XML 문서 주석은 공개 구성원을위한 것입니다.

경고 컴파일러 분명이 상태 :

공개적으로 보이는 유형 또는 멤버 'Type_or_Member'에 대한 XML 주석이 누락되었습니다.

해당 구성원의 이름이 아직 명확하지 않은 경우 개인 구성원에게만 XML 주석을 추가해야합니다.

여기에 순수한 의견이 있으니 가치가 있다고 생각하십시오.

나는 불필요한 XML 주석이 싫어 . 메소드 / 프로퍼티 이름에 공백을 추가하는 고스트 닥 스타일 스타일의 경우도 마찬가지입니다. 그것은 가치를 추가하지 않고 단순히 실제 코드에 대한 나의 견해를 복잡하게 만듭니다.

설명이 필요한 경우 반드시 의견을 말하십시오. 그러나 의미있는 이름을 가진 작은 집중된 방법으로 많은 명확성을 전달할 수 있습니다. 코드를 개선하고 주석을 불필요하게 만들 수 있으면 주석을 달지 마십시오.

심지어 나 불필요한 사용을 시작하지 마십시오 this.과 Me..

부수적으로, XML 주석의 가시성을 토글 할 수있는 Visual Studio addin을 갖고 싶습니다. (힌트 힌트)

@SLaks가 언급했듯이 공개 멤버의 XML 문서는 상당히 장황하고 완벽해야합니다.

그러나 Visual Studio는 인텔리전스를 채우고 툴팁을 XML 문서 주석으로 도울 수 있기 때문에 개인, 보호 또는 내부 구성원에게도 실제로 유용 할 수 있습니다.

이것은 다음을 의미합니다.

// describe what this does
private void DoSomething() 
{
    // or describe it here...

완벽하게 충분한 문서 일 수 있지만 다음을 수행하십시오.

/// <summary>describe what this does</summary>
private void DoSomething() 
{

코드의 다른 곳에서 빠르게 볼 수 있습니다.

일반적으로 공개 XML 주석에 대해서는 API의 일부 외부 사용자를 위해 작성하고 내부 XML 주석에 대해서는 저 또는 다른 팀을 위해 작성하고 있습니다.

매개 변수 설명을 건너 뛰는 것은 아마도 전자에게는 좋지 않은 것이고 후자에게는 좋습니다.

난 항상 여부를 포함한다 (특히 공공 API 문서에) 추가 할 수 get또는 set속성 :

/// <summary>Gets a value indicating whether an item is selected.</summary>
public bool ItemIsSelected
{ 
    get { return SelectedItem != null; } 
}

그것은 여부를 C #의 인텔리에서 분명 아니다 get또는 set사용할 수 있지만 XML 주석에 퍼팅하면 툴팁에서 한 눈에 알 수 있습니다 의미합니다.