Commenti di 2a o 3a persona?

Question

Scrivi commenti in 2a o 3a persona?

// go somewhere and do something (2nd person comment) 

o

// goes somewhere and does something (3rd person comment) 

Answer 1

Sicuramente terza persona stile.

Answer 2

spesso tendono a parlare stile medico:

// Now we take $x and check whether it's valid for this pass 

Answer 3

Un utile consiglio: cercate di mantenere ogni commento come autosufficiente possibile. Ad esempio, questo modulo:

// First, mumble the frabbitz. 

blah blah 

// Second, foobar the quux 

blah blah 

questo è un bel racconto, ma rende più difficile per modificare il codice, perché le parti "Prima" e "seconda" può diventare non corretta. Alla fine, non aggiungono molto ai commenti, ma li rendono correlati in modo fragile.

Answer 4

volte mi parlano in prima persona, come questo

/* 
Usage: 
set_position(0.5, 0.5); // im in the center 
set_position(0.0, 1.0); // im in the lower,left corner 
*/ 

Answer 5

Può dipendere da quante persone stanno modificando il codice e per quale scopo. Nel mio codice (che è comunque per la visione pubblica) potrei sentirmi libero di aggiungere alcuni commenti personali, magari usando "Io". In un progetto comune i commenti dovrebbero mirare a uno stile comune e l'io potrebbe essere fuori luogo.

Si noti che i commenti sono fragili e molte autorità moderne (ad es. Clean Code) suggeriscono che le funzioni e i campi dovrebbero portare nomi significativi. Ma, naturalmente, ci sono molti posti in cui i commenti esplicativi sono ancora vitali.

Answer 6

La mia opinione è che dovresti semplicemente usare lo stile con cui ti senti più a tuo agio.

I commenti incorporati sono intesi per essere letti da te e da altri sviluppatori che cercano di capire i dettagli di implementazione del tuo codice. Fintanto che sono chiari e comprensibili, è importante se lo stile è un po 'insolito, la grammatica è un po' scadente o ci sono alcuni errori di ortografia. La gente che sta leggendo dovrebbe essere al di là di prendersi cura di queste cose.

I commenti che vengono estratti per formare la documentazione API meritano un po 'più attenzione alle sottigliezze di stile, grammatica e ortografia. Ma anche qui accuratezza e completezza sono molto più importanti.