XML 문서 속성에 "Gets or sets .."가 필요합니까?

C #에서 XML 주석에 대한 모범 사례 권장 사항을 찾고 있습니다. 속성을 만들 때 예상되는 XML 설명서의 형식은 다음과 같습니다.

/// <summary>
/// Gets or sets the ID the uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID {
    get;
    set;
}

속성의 서명이 이미 알려줍니다하지만 이후 (이 경우에는 둘 다있는 클래스의 외부 클라이언트가 사용할 수있는 작업 get과 set의견이 너무 수다스러운이며, 그 아마도 다음은 충분한 것 같은 느낌)

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID {
    get;
    set;
}

Microsoft는 첫 번째 양식을 사용하므로 암시적인 규칙처럼 보입니다. 그러나 나는 두 번째 것이 내가 언급 한 이유로 더 낫다고 생각합니다.

나는이 질문이 건설적이지 않은 것으로 표시되기에 충분하다는 것을 이해하지만, 언급해야 할 속성의 양은 엄청 나기 때문에이 질문이 여기있을 권리가 있다고 생각합니다.

공식 권장 관행에 대한 아이디어 나 링크에 감사드립니다.

서명은 다른 코드 조각에 사용 가능한 작업을 알려줄 수 있습니다. 그러나 이들은 작업하면서 코더에게 명확하게 표시되지 않으며 XML 문서는 사람들이 컴파일러를 사용하지 않고 소비하기위한 것입니다.

이 수업을 예로 들어 보겠습니다.

public class MyClass
{
    /// <summary>
    /// The first one
    /// </summary>
    public int GetOrSet { get; set; }

    /// <summary>
    /// The second one
    /// </summary>
    public int GetOnly { get; private set; }

    /// <summary>
    /// The last one
    /// </summary>
    public int SetOnly { set; private get; }
}

이러한 속성 중 하나에 액세스하기 위해 인텔리전스를 가져 오면 어떤 속성을 쓰거나 읽을 수 있는지 또는 둘 다에 대한 표시가 없습니다.

마찬가지로 문서를 볼 때도 확실하지 않습니다.

따라서 우리는 추가 가져 오거나 설정 , 취득 , 또는 세트 코드를 작성하는 동안 프로그래머에 더 쉽게 할 수 있습니다. 예상대로 데이터를 다시 속성에 쓸 수 없다는 것을 알기 위해 일부 데이터를 읽고 처리하는 큰 코드 블록을 작성하지는 않을 것입니다.

StyleCop은 Gets or Sets ...규칙 SA1623에 적용 되는 표기법을 사용합니다 .

링크 된 페이지에는 목록에없는 다른 사례가 나열됩니다.

/// <summary>
/// Gets a value indicating whether the item is enabled.
/// </summary>
public bool Enabled
{
    get { return this.enabled; }
}

당신이 나열하는 다른 옵션이 있습니다.

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID { get; set; }

vs

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID { get; }

속성이 읽기 전용하는 인텔리 힌트에 대한 정보를 제공 할 것이다, 당신도이 경우에 대한 규칙을 가지고 올 수 있지만 Gets ..., Gets or Sets...잘 IMO 작업을 수행합니다.

StyleCop 규칙에 나열된 다른 변형이 Gets or Sets...있지만이 를 사용하면 명확 하지만 그렇지 않을 수도 있습니다.

또한 Doxygen 또는 Sandcastle과 같은 문서를 생성 할 때 전체 표기법으로 API를 더 잘 문서화 할 수 있습니다.

XML 주석에서 속성 가져 오기 및 설정에 대한 정보를 추가하는 유일한 경우는 예상대로 동작하지 않을 때뿐입니다 (똑바로 공개 get 및 설정).

비공개이거나 추가 논리가 포함되어 있으면 언급하고, 그렇지 않으면 속성의 의도를 문서화합니다.

더 자세한 버전으로 더 행복 할 것입니다.

다른 하나는 카운터 변수를 증가시킨 후 "증가 카운터"에 대한 주석을 갖는 것과 같습니다.

Get and Set이 있음이 분명합니다. 비공개 세터가있는 경우 비공개 키워드를 사용하는 것이 분명합니다.

주석은 코드의 실제 주석 버전이 아니라 가치를 추가해야합니다.