Quali sono i tuoi pensieri su Periodi / Punti completi nei commenti al codice? [chiuso]

Il punto è la separazione delle frasi. Se un commento consiste di una sola frase circondata da codice, non è necessario interrompere completamente. A volte persino non capitalizzo la 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 scritto dall'OP, "punti fermi") nei vostri commenti di codice?

Per mantenerlo pertinente, perché?

Per la stessa ragione li aggiungo scrivendo testo "normale" - fanno parte della lingua in scrittura, e non dovrebbero esserci nulla di speciale su di loro. Li uso allo stesso modo quando si scrivono commenti di una frase (una riga) e interi paragrafi.

Il codice sorgente non è un testo normale, quindi usiamo regole diverse per questo. Semplice; -)

Se scrivi commenti, speri che siano scritti in inglese. In questo caso, si dovrebbe puntare correttamente. Fare altrimenti sarebbe pigro.

Se scrivo una frase completa (o più), allora sì. Se non lo faccio, a volte no, ma di solito si ancora.

A volte impazzisco e uso punti esclamativi, punti interrogativi, ecc.)

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

Le altre risposte e la loro popolarità hanno chiarito che i fermi completi sono ben apprezzati nei commenti più lunghi e probabilmente possono essere evitati nelle battute a una mano.

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

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

e

    // This code really sucks!

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

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

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

Perché? - Simile al motivo per cui scrivo email usando una scrittura corretta, mentre potrei usare frasi stenografiche nei messaggi SMS. In un caso sono seduto per scrivere un blocco di testo corretto, quindi automaticamente lo faccio "correttamente", mentre nell'altro è solo una breve nota per ottenere un punto.

Esempi reali dal mio codice:

Commento rapido:

// 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 consentire a una terza persona di rivedere il tuo codice.

Durante la creazione di commenti XML , eseguirò sempre correttamente la maiuscola e la punteggiatura che mi aspetto di vedere in IntelliSense e nei nostri generati documentazione . 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.