Cosa ne pensi di Periodi / Soste complete nei commenti sul codice? [chiuso]

Ho visto questo fatto nella SO Tavern , quindi sto postando la domanda qui. Ho pensato che fosse una domanda interessante. (Ovviamente non appartiene a SO, ma penso che sia OK qui.)

Aggiungete punti (o, come ha scritto l'OP, "punti fermi") nei vostri commenti sul codice?

Per mantenerlo rilevante, perché ?

Il punto fermo serve per terminare le frasi, ma se un commento è costituito da una sola frase circondata da un codice, a mio avviso non è necessario un punto pieno. A volte non faccio mai lettere maiuscole nella prima lettera. Un commento multilinea dettagliato, d'altra parte, ha bisogno di punteggiatura completa.

// This function returns an average of two integers. Note that it may
// return an irrelevant result if the sum of a and b exceeds the int
// boundaries.

int avg(int a, int b)   // make it static maybe?
{
    // A better algorithm is needed that never overflows
    return (a + b) / 2; 
}

Sì, perché i commenti sono in inglese e l'inglese corretto utilizza la punteggiatura.

Aggiungete punti (o, come ha scritto l'OP, "punti fermi") nei vostri commenti sul codice?

Per mantenerlo rilevante, perché?

Per lo stesso motivo, li aggiungo quando scrivo un testo "normale" - fanno parte della lingua per iscritto e non dovrebbero esserci nulla di speciale in loro. Li uso ugualmente quando scrivo una frase (una riga) e interi paragrafi.

Il codice sorgente non è un testo normale e pertanto utilizziamo regole diverse per esso. Semplice ;-)

Se scrivi commenti, si spera che siano scritti in inglese. Stando così le cose, si dovrebbe punteggiare correttamente. Fare diversamente sarebbe pigro.

Se scrivo una frase completa (o più), allora sì. In caso contrario, a volte no, ma di solito comunque sì.

A volte impazzisco e utilizzo punti esclamativi, punti interrogativi, ecc .;)

Per quanto riguarda il motivo, è in parte perché sono proprio così e in parte perché trovo che la punteggiatura appropriata possa aggiungere molta chiarezza.

Le altre risposte e la loro popolarità hanno chiarito che i punti pieni sono apprezzati nei commenti più lunghi e probabilmente possono essere evitati in una riga.

Un altro punto che potrebbe essere rilevante è quello di evitare i punti esclamativi, in particolare i multipli . Esempio:

    // Though loop is labor-intensive, performance is fine with with 95K cases!!!

e

    // This code really sucks!

D'altra parte, a volte i punti interrogativi sono piuttosto utili:

    // TODO: What does Crojpler.bway() actually do?

Dipende. Se scrivo un paragrafo grande e appropriato che spiega cosa fa un blocco di codice, allora lo punteggio correttamente, come qualsiasi altro pezzo di scrittura corretta. OTOH, quando commento solo una singola riga di codice, allora non lo faccio.

Perché? - Simile al motivo per cui scrivo e-mail usando la scrittura corretta, mentre potrei usare frasi abbreviate nei messaggi SMS. In un caso mi siedo per scrivere un blocco di testo adeguato, quindi lo faccio automaticamente "correttamente", mentre nell'altro è solo una breve nota per ottenere un punto.

Veri esempi dal mio codice:

Commento rapido della nota:

// check for vk_enter

Documentazione del metodo "corretta":

// This method sets up a workspace tab with the given name. Each MDI window has a parent
// workspace specified when it's saved. The code which loads each MDI window then point it to
// the correct workspace.

Sì, penso che in questo modo crei una buona convenzione di codifica e crei anche un codice leggibile per una terza persona che revisiona il tuo codice.

Sarò sempre correttamente capitalizzare e punteggiano durante la creazione di commenti XML che mi aspetto di essere visto in IntelliSense e nella nostra documentazione generata . Questi sono costrutti molto più formali e dovrebbero essere trattati come tali.

I commenti appena visti nel corpo di un blocco di codice, tuttavia, dovrebbero essere semplicemente il più chiari possibile. Spetta al programmatore come ottenerlo.