Eu costumava gostar de exigir comentários XML para documentação. Desde então, mudei de idéia por dois motivos principais:
- Como um bom código, os métodos devem ser auto-explicativos.
- 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; }
}
Respostas:
Se seus comentários forem assim apenas:
Então sim, eles não são tão úteis. Se eles lerem algo como isto:
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 quantoThis 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).
fonte
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
UnitOfMeasure
paranull
é 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 deLabelSerialNumber
se difere do de uma planícieInt32
: 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.* ... nesse caso,
uint
pode ser uma escolha melhorfonte
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.
fonte