Comentários XML são documentação necessária?

Eu costumava gostar de exigir comentários XML para documentação. Desde então, mudei de idéia por dois motivos principais:

1. Como um bom código, os métodos devem ser auto-explicativos.
2. Na prática, a maioria dos comentários XML são ruídos inúteis que não fornecem valor adicional.

Muitas vezes, simplesmente usamos o GhostDoc para gerar comentários genéricos, e é isso que quero dizer com ruído inútil:

    /// <summary>
    /// Gets or sets the unit of measure.
    /// </summary>
    /// <value>
    /// The unit of measure.
    /// </value>
    public string UnitOfMeasure { get; set; }

Para mim, isso é óbvio. Dito isto, se houver instruções especiais a serem incluídas, devemos usar absolutamente comentários XML.

Eu gosto deste trecho deste artigo :

Às vezes, você precisará escrever comentários. Mas, deve ser a exceção, não a regra. Os comentários devem ser usados ​​apenas quando expressam algo que não pode ser expresso em código. Se você deseja escrever um código elegante, lute para eliminar comentários e, em vez disso, escreva um código de auto-documentação.

Estou errado ao pensar que só devemos usar comentários XML quando o código não é suficiente para se explicar por conta própria?

Acredito que este seja um bom exemplo em que os comentários XML tornam o código bastante feio. É preciso uma aula como esta ...

public class RawMaterialLabel : EntityBase
{
    public long     Id                      { get; set; }
    public string   ManufacturerId          { get; set; }
    public string   PartNumber              { get; set; }
    public string   Quantity                { get; set; }
    public string   UnitOfMeasure           { get; set; }
    public string   LotNumber               { get; set; }
    public string   SublotNumber            { get; set; }
    public int      LabelSerialNumber       { get; set; }
    public string   PurchaseOrderNumber     { get; set; }
    public string   PurchaseOrderLineNumber { get; set; }
    public DateTime ManufacturingDate       { get; set; }
    public string   LastModifiedUser        { get; set; }
    public DateTime LastModifiedTime        { get; set; }
    public Binary   VersionNumber           { get; set; }

    public ICollection<LotEquipmentScan> LotEquipmentScans { get; private set; }
}

... E transforma isso:

/// <summary>
/// Container for properties of a raw material label
/// </summary>
public class RawMaterialLabel : EntityBase
{
    /// <summary>
    /// Gets or sets the id.
    /// </summary>
    /// <value>
    /// The id.
    /// </value>
    public long Id { get; set; }

    /// <summary>
    /// Gets or sets the manufacturer id.
    /// </summary>
    /// <value>
    /// The manufacturer id.
    /// </value>
    public string ManufacturerId { get; set; }

    /// <summary>
    /// Gets or sets the part number.
    /// </summary>
    /// <value>
    /// The part number.
    /// </value>
    public string PartNumber { get; set; }

    /// <summary>
    /// Gets or sets the quantity.
    /// </summary>
    /// <value>
    /// The quantity.
    /// </value>
    public string Quantity { get; set; }

    /// <summary>
    /// Gets or sets the unit of measure.
    /// </summary>
    /// <value>
    /// The unit of measure.
    /// </value>
    public string UnitOfMeasure { get; set; }

    /// <summary>
    /// Gets or sets the lot number.
    /// </summary>
    /// <value>
    /// The lot number.
    /// </value>
    public string LotNumber { get; set; }

    /// <summary>
    /// Gets or sets the sublot number.
    /// </summary>
    /// <value>
    /// The sublot number.
    /// </value>
    public string SublotNumber { get; set; }

    /// <summary>
    /// Gets or sets the label serial number.
    /// </summary>
    /// <value>
    /// The label serial number.
    /// </value>
    public int LabelSerialNumber { get; set; }

    /// <summary>
    /// Gets or sets the purchase order number.
    /// </summary>
    /// <value>
    /// The purchase order number.
    /// </value>
    public string PurchaseOrderNumber { get; set; }

    /// <summary>
    /// Gets or sets the purchase order line number.
    /// </summary>
    /// <value>
    /// The purchase order line number.
    /// </value>
    public string PurchaseOrderLineNumber { get; set; }

    /// <summary>
    /// Gets or sets the manufacturing date.
    /// </summary>
    /// <value>
    /// The manufacturing date.
    /// </value>
    public DateTime ManufacturingDate { get; set; }

    /// <summary>
    /// Gets or sets the last modified user.
    /// </summary>
    /// <value>
    /// The last modified user.
    /// </value>
    public string LastModifiedUser { get; set; }

    /// <summary>
    /// Gets or sets the last modified time.
    /// </summary>
    /// <value>
    /// The last modified time.
    /// </value>
    public DateTime LastModifiedTime { get; set; }

    /// <summary>
    /// Gets or sets the version number.
    /// </summary>
    /// <value>
    /// The version number.
    /// </value>
    public Binary VersionNumber { get; set; }

    /// <summary>
    /// Gets the lot equipment scans.
    /// </summary>
    /// <value>
    /// The lot equipment scans.
    /// </value>
    public ICollection<LotEquipmentScan> LotEquipmentScans { get; private set; }
}

Se seus comentários forem assim apenas:

/// <summary>
/// Gets or sets the sublot number.
/// </summary>
/// <value>
/// The sublot number.
/// </value>

Então sim, eles não são tão úteis. Se eles lerem algo como isto:

/// <summary>
/// Gets or sets the sublot number.
/// Note that the sublot number is only used by the legacy inventory system.
/// Latest version of the online inventory system does not use this, so you can leave it null. 
/// Some vendors require it but if you don't set it they'll send a request for it specifically.
/// </summary>
/// <value>
/// The sublot number.
/// </value>

Então eu diria que eles têm valor. Portanto, para responder à sua pergunta: Os comentários são necessários quando eles dizem algo que o código não diz.

Uma exceção: é bom ter comentários sobre qualquer coisa que seja acessível ao público se você estiver escrevendo uma biblioteca / API que estará disponível para o público. Eu odeio usar uma biblioteca e ver uma função nomeada getAPCDGFSocket()sem explicação do que é um APCDGFSocket (eu ficaria feliz com algo tão simples quanto This gets the Async Process Coordinator Data Generator File Socket). Portanto, nesse caso, eu diria que use alguma ferramenta para gerar todos os comentários e, em seguida, ajuste manualmente os que precisam (e verifique se seus acrônimos criptográficos são explicados).

Além disso, getters / setters geralmente são maus exemplos para "os comentários são necessários?" porque geralmente são bastante óbvios e comentários não são necessários. Os comentários são mais importantes em funções que executam algum algoritmo, onde algumas explicações de por que as coisas estão sendo feitas da maneira como estão podem tornar o código muito mais compreensível e também facilitar o trabalho de futuros programadores.

... e, finalmente, tenho certeza de que essa pergunta é relevante para todos os estilos de comentários, não apenas para aqueles que são formatados usando XML (que você está usando porque está trabalhando em um ambiente .NET).

Os comentários que parecem inúteis para usuários que podem ler o código se tornam bastante úteis para usuários que não têm acesso à fonte. Isso acontece quando a classe é usada como API externa por pessoas de fora da sua organização: os HTMLs gerados a partir de seus documentos XML são a única maneira de aprender sobre suas aulas.

Dito isto, um comentário que reitera o nome do método com espaços adicionais entre as palavras permanece inútil. Se sua turma for usada fora de sua organização, é necessário documentar para que os intervalos válidos para seus valores não sejam válidos. Por exemplo, você deve dizer que a configuração UnitOfMeasurepara nullé ilegal, que o valor fornecido ao setter não deve conter espaços no início ou no final da string e assim por diante. Você também deve documentar o intervalo de LabelSerialNumberse difere do de uma planície Int32: talvez não permita números negativos ^*, ou não permite mais de sete dígitos. Seus usuários internos podem considerar isso um dado adquirido, porque analisam os números de série dia após dia, mas os usuários externos podem ficar genuinamente surpresos ao ver uma exceção do que parece um setter inocente.

Você está absolutamente certo em evitar esses comentários inúteis. Eles tornam a leitura do código mais difícil, em vez de facilitar, e estão ocupando muito espaço.

Na minha prática, as pessoas que escrevem comentários com getters / setters, tendem a omitir comentários quando são realmente necessários (como construir uma consulta sql de 20 linhas para um componente sem documentação).

Escrevo comentários quando existem outras soluções óbvias - indico por que exatamente essa abordagem foi usada. Ou quando é difícil entender a ideia sem conhecer todos os detalhes - listo brevemente os detalhes necessários para entender o código.

O exemplo que você dá é mais sobre escrever comentários para dizer que alguém escreve comentários do que para facilitar a vida dos outros (e deles também).

BTW, você pode melhorar sua capacidade de escrever comentários retornando ao seu código antigo e tentando compreendê-lo (você pode até não reconhecer seu próprio código em 2 a 3 meses - é absolutamente como ler o código de outra pessoa). Se você fizer isso sem dor, tudo estará bem.