"I", "We" o Né nella documentazione del codice

41

Mi ritrovo a scrivere (si spera) utili commenti nella documentazione del codice (C ++) del tipo:

The reason we are doing this is...

Il motivo per cui uso "noi" anziché "io" è perché faccio molta scrittura accademica dove "noi" è spesso preferito.

Quindi ecco la domanda. C'è un buon motivo per preferire l'uno all'altro nel documentare il codice:

Usa "Noi": il motivo per cui lo stiamo facendo è ...
Usa "I": il motivo per cui lo sto facendo è ...
Usa il mio nome: il motivo è [my name]stato questo ...
Voce passiva: il motivo per cui è stato fatto è ...
Né: fallo perché ...

Ho scelto il n. 1 perché sono abituato a scrivere in quel modo, ma la documentazione non è per lo scrittore, è per il lettore, quindi mi chiedo se l'aggiunta del nome dello sviluppatore sia utile o se ciò aggiunga solo un'altra cosa che deve essere modificato quando si mantiene il codice.

documentation

— Alan Turing
fonte

Penso che dipenda dalle preferenze personali. Non vedo alcun motivo per cui uno sarebbe più chiaro dell'altro in generale.

— ConditionRacer

6

Che ne dici di # 5: "Quando nel corso di eventi umani ...";)

— ceretta il

8

"Quattro punti e sette secondi fa i nostri antenati hanno appreso che il foo deve essere escluso, almeno le nostre forze devono essere superate con NULL"

— Philip

Fortemente legato all'inglese.SE: perché i programmatori usano sempre "noi" quando in realtà significano "io" o "tu"? (Che, purtroppo, è stato chiuso)

— Izkata

2

Perché non dirlo This code was written like this because...? (Voce passiva)

— Alvin Wong

77

Vorrei andare con:

# 6. Dichiarativo: ...

Piuttosto che dire "La ragione è stata perché ogni Foo deve avere un Bar", dì semplicemente "Ogni Foo deve avere un Bar". Trasforma il commento in un'affermazione 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 althe reason this was done frase non aggiunge alcuna informazione. Inoltre evita esattamente il problema che stai riscontrando.

— Bobson
fonte

ti dispiacerebbe approfondire un po 'perché dovresti farlo? Senza una spiegazione, questa risposta sembra più un'opinione nuda, in qualche modo in conflitto con le linee guida di backup : '... L'opinione non è affatto negativa, a condizione che sia supportata da qualcosa di diverso da "perché sono un esperto" o "perché l'ho detto" o "solo perché". Usa le tue esperienze specifiche per sostenere le tue opinioni, come sopra, o indica alcune ricerche che hai fatto sul web o altrove che forniscono prove a sostegno delle tue affermazioni ... '

— moscerino

15

@gnat "Il motivo è stato fatto" non aggiunge nulla alla spiegazione. I commenti dovrebbero contenere solo testo sufficiente per ottenere il punto e non più. Lascia fuori le prelibatezze, i preamboli e altro testo di riempimento.

— David Harkness,

@gnat - In realtà avevo appena finito di aggiungere altro quando ho visto il tuo commento.

— Bobson

1

Penso che il mio esempio sia stato troppo semplicistico, perché in effetti "la ragione per cui è stato fatto" non aggiunge nulla. Ma ci sono casi in cui una situazione difficile richiede qualche spiegazione, e in quel caso, trovo più naturale usare "noi" o "io", proprio come ho usato "io" più volte in questo commento. Ma penso che la tua risposta sia chiara nello spirito: "dichiarativo" suggerisce: usa il minor numero di parole che capiscono chiaramente il punto.

— Alan Turing,

7

Ho letto //come becausenella maggior parte dei casi.

— Ilmo Euro

23

Preferisco nessuno dei due, e in realtà tralascerei del tutto questa frase introduttiva e arriverei al punto. Cerco anche di evitare di dire "questo" perché non lascia modo di dire 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 tu stia aggiungendo un commento implica che stai dichiarando un motivo, quindi non devi dire ridondantemente alle persone che stai spiegando il motivo. Rendi il motivo il più specifico possibile, in modo che sappiano il più chiaramente possibile come mantenere quel codice in un secondo momento.

— Karl Bielefeldt
fonte

4

In C # (e nella maggior parte degli strumenti di documentazione in altre lingue) c'è una differenza tra documentazione e commenti in linea. La mia opinione personale è che dovresti sempre usare commenti formali, in stile dichiarativo, come suggeriscono Bobson e altri 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 nello spiegare perché qualcosa viene donato rispetto a una completa esposizione in inglese formale.

Ecco un esempio che penso 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);
    ...
}

— pswg
fonte

4

Nota a margine: SanitizeDatadovrebbe restituire a SafeComplexObject. ;)

— Jon Purdy

Sono d'accordo, ma preferisco i commenti letterali (piuttosto che metaforici), soprattutto se potrebbero esserci sviluppatori con background linguistici diversi.

— John B. Lambe,

2

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

I commenti non cambiano sempre quando il codice viene modificato, il che può causare confusione in seguito.
I test delle unità offrono al manutentore un modo semplice per giocare con il codice. L'apprendimento di una nuova base di codice può essere molto più semplice se si dispone di singole unità che è possibile interrompere per osservare cosa cambia.

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

— mortalapeman
fonte

1

I buoni commenti sono difficili da scrivere e anche i commenti migliori sono spesso difficili da leggere e comprendere. Se il tuo commento è abbastanza conciso per me da assorbire e abbastanza preciso da comunicare ciò che devo sapere sul codice, non fa alcuna differenza quali pronomi usi.

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

— John M Gant
fonte

Vorrei chiarire: per i commenti che entreranno a far parte della documentazione formale, è appropriato un tono più formale e "io" e "noi" sono meglio evitare. Quello che avevo in mente con questa risposta era il commento esplicativo occasionale, ad esempio quando hai fatto qualcosa che sembrerà sbagliato al prossimo ragazzo. In quei casi, dove solo le persone che lavorano nella stessa base di codice lo vedranno mai, dico di fare qualunque cosa trasmetterà il tuo significato più chiaramente, anche se lo è I wrote the code this way because...o what we really need here is.... In questi casi, un commento chiaro è più importante di uno stile rigoroso.

— John M Gant,

1

Il motivo per cui uso "noi" anziché "io" è perché faccio molta scrittura accademica dove "noi" è spesso preferito.

È uno stile cattivo, anche per documenti 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 vorrei lasciare questo commento, a meno che non inizi con:

// TODO: clean this up, ...

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

— BЈовић
fonte