"I", "Noi" o Nulla nella documentazione del codice

Vorrei andare con:

# 6. Dichiarativo: ...

Piuttosto che dire "Il motivo per cui questo è stato fatto è che ogni Foo deve avere una barra", basta dire "Ogni Foo deve avere una barra". Rendi il commento in una dichiarazione attiva della ragione, piuttosto che passiva. Generalmente è uno stile di scrittura migliore nel complesso, si adatta meglio alla natura del codice (che fa qualcosa), e la frase the reason this was done non aggiunge alcuna informazione. Evita anche esattamente il problema che stai incontrando.

Non preferisco nessuno dei due, e in realtà eliminerei del tutto quella frase introduttiva e arriverei al punto. Cerco anche di evitare di dire "questo" perché non consente di stabilire se il commento è sincronizzato con il codice. In altre parole, invece di:

// The reason this was done is to prevent null pointer exceptions later on.

Direi:

// Frobnicate the widget first so foo can never be null.

Il fatto che stai aggiungendo un commento implica che stai affermando una ragione, quindi non devi dire in modo ridondante alle persone che stai spiegando il motivo. Basta rendere il motivo il più specifico possibile, in modo da sapere il più chiaramente possibile come mantenere quel codice in seguito.

In C # (e nella maggior parte degli strumenti di documentazione in altre lingue) c'è una differenza tra la documentazione e i commenti in linea. La mia opinione personale è che dovresti sempre usare commenti formali in stile dichiarativo come Bobson e altri suggerire nella documentazione di una classe o di un membro, ma all'interno del codice non c'è nulla di sbagliato nell'essere meno formale. In effetti, a volte un commento informale è più efficace per spiegare perché qualcosa è don più di un'esposizione completa in inglese formale.

Ecco un esempio che, a mio avviso, illustra il punto.

/// <summary>
/// Takes data from the remote client and stores it in the database.
/// </summary>
/// <param name="data">The data to store.</param>
public void StoreData(ComplexObject data)
{
    // Don't take candy from strangers
    ComplexObject safeData = SanitizeData(data);
    ...
}

Un'altra idea da considerare sarebbe un test unitario ben realizzato che dimostra perché il codice funziona come al posto di scrivere un commento descrittivo. Questo ha un paio di vantaggi rispetto alla scrittura di commenti:

1. I commenti non cambiano sempre quando il codice viene modificato, il che può portare a confusione più tardi.

2. I test di unità danno al manutentore un modo semplice di giocare con il codice. Imparare una nuova base di codice può essere molto più semplice se si dispone di unità individuali che è possibile interrompere per osservare quali modifiche.

Anche se questa strada richiede più lavoro in anticipo, i test unitari possono essere un'ottima forma di documentazione.

I buoni commenti sono difficili da scrivere e anche i migliori commenti sono spesso difficili da leggere e comprendere. Se il tuo commento è abbastanza sintetico da essere assorbito e abbastanza preciso da trasmettere ciò che ho bisogno di sapere sul codice, non mi fa alcuna differenza che pronomi usi.

Mi dispiacerebbe scoraggiare qualcuno dal commentare il loro codice perché sono preoccupati per il caso, il tempo e la persona dei loro pronomi.

The reason I use "we" instead of "I" is because I do a lot of academic writing where "we" is often preferred.

È uno stile pessimo, anche per i titoli accademici, a meno che tu non stia cercando di nascondere chi ha effettivamente deciso quel punto esatto.

Per quanto riguarda la tua domanda specifica: non lascerei questo commento, a meno che non inizi con:

// TODO: clean this up, ...

o a meno che non spieghi qualcosa di molto importante, potrebbe non essere così chiaro dal codice. In tal caso, rendere il commento il più breve possibile.