I commenti .net iniziano con una lettera maiuscola e terminano con un punto?

Question

A seconda del feedback che ottengo, potrei alzare questo "standard" con i miei colleghi. Potrebbe diventare una regola StyleCop personalizzata. c'è già uno scritto?

Quindi, Stylecop impone già questo per i tag di documentazione summary, param e return.

Pensi che abbia senso richiedere lo stesso dai commenti?

Sulla nota correlata: se un commento è già lungo, dovrebbe essere scritto come frase corretta?

Per esempio (forse ho cercato troppo duro per illustrare un commento cattivo):

//if exception quit 

vs.

// If an exception occurred, then quit. 

Se figurato - la maggior parte del tempo, se si preoccupa di scrivere un commento , quindi potrebbe anche essere informativo. Considerare questi due campioni:

//if exception quit 
if (exc != null) 
{ 
    Application.Exit(-1); 
} 

e

// If an exception occurred, then quit. 
if (exc != null) 
{ 
    Application.Exit(-1); 
} 

Probabilmente, uno non ha bisogno di un commento a tutti, ma dal momento che uno è fornito, penserei che la seconda è meglio.

Esprimete il vostro parere. Hai un buon riferimento per l'arte del commentare, in particolare se si riferisce a .Net?

Grazie.

Answer 1

Spesso scrivo commenti che sono semplicemente pensati per aiutarmi a trovare sezioni di codice. (Io uso anche le regioni di questo.) Ad esempio:

// SERVER

Perché l'IDE colora commenti, rende a portata di mano, a volte di avere brevi commenti come questo per aiutare nelle cose che bloccano mentalmente in segmenti. Solitamente lo faccio solo per una decina di linee di codice. Se è più lungo, allora un #region sembra migliore.

ho spesso scrivere note nei miei commenti, a volte come un punto di riferimento per me in questo modo:

// NOTE: -273.15 is absolute zero in °C, used for a MinValue below

Non è una frase grammaticalmente bello o completa, ma ha senso.

Dove Io tendo ad usare più completo, frasi strutturate è nella sintesi dei miei metodi, in questo modo:

/// <summary> 
/// Populates the properties of a Sensor object based on 
/// the XML components of its data file. 
/// </summary> 

Quelli che sento hanno maggiori probabilità di essere letto da qualcun altro e aiuta ad avere la verbosità e pulisci la formattazione.

Answer 2

Il tempo per scrivere commenti chiari, leggibili e comprensibili non viene mai sprecato. Quante volte ho riletto i miei commenti in un secondo momento solo per faticare a capirli. Le persone che scrivono commenti scarsamente formattati spesso appiano gli stessi tratti al loro codice.

Answer 3

Se il codice ha bisogno di un commento, allora dovrebbe essere ben formato, perché IMO probabilmente c'è un concetto (non banale) che deve essere spiegato.

I commenti banali come nei tuoi esempi dovrebbero essere evitati. Non aggiungono altro che rumore.

Answer 4

se si commentano i metodi in Visual Studio si dovrebbe considerare l'utilizzo del riepilogo e dei parametri nella parte superiore del metodo. In questo modo hai dettagli sul metodo durante il codice completo. Ecco un esempio

/// <summary> 
    /// you summary here 
    /// </summary> 
    /// <param name="param1">Describe parameter usage</param> 
    /// <param name="param2">Describe parameter usage</param> 

Answer 5

Ho scoperto che quando cerco di essere breve con i commenti (cioè frasi incomplete, frammenti), spesso mi lascio fuori presupposti chiave o parole che sarebbe in realtà chiarire significato. Al momento non riesco a trovare un esempio concreto, mi dispiace.

In generale, però, costringerti a scrivere frasi complete e appropriate ti costringe anche a pensare di più a ciò che stai cercando di dire con il commento. Mi sono spesso sorpreso a ripensare a ciò che voglio davvero includere in un commento scrivendolo per intero.

Non c'è una buona ragione per sacrificare la chiarezza all'altare della brevità. Qualcuno dovrà capire il codice in futuro. I commenti sono per loro, quindi rendili facili da digerire.