Per i commenti sul controllo della versione cosa fanno / raccomandano gli altri utenti - passato o presente?

ie

• Modificato x in y.
• o
• Cambiando x per essere y.

I commenti devono essere letti nel contesto, quindi:

Presente

Per i commenti di origine sopra un metodo o prima che si verifichi un comportamento:

// This function does X
function doX() { ... }

Passato

Per i commenti di origine dopo che si è verificato un comportamento

function doX() {
    widget.doY()
    // did Y to widget to prepare it for Z
    ...
}

E per i messaggi di commit

la funzione X è cambiata

Esempio misto:

// This function does X
function doX() {
    widget.doY()
    // did Y to widget to prepare it for Z
    ....
}

Passato - Dal momento che chiunque lo leggerà in futuro farà riferimento all'atto del cambiamento come è accaduto in passato.

Formattare qualcosa come "Modifica" implica che si sta attualmente effettuando la modifica e che il codice potrebbe non essere completato.

nota: Personalmente, ho inserito commenti di modifica solo quando si è verificato un cambiamento drastico.

I commenti sono cose statiche, quindi dovrebbero presentare lo stato del programma così com'è e non come sarà. Per rispondere alla tua domanda specifica, sarebbe più appropriato usare il passato .

Tuttavia, questo tipo di commento è più adatto al sistema di controllo della versione. Il controllo della versione svolge un lavoro molto migliore nel rilevamento delle modifiche rispetto ai commenti manuali. Con i sistemi di controllo della versione, è più appropriato documentare al momento presente poiché tali commenti si applicano al momento del commit della modifica. Ma entrambi funzioneranno.

Consiglio vivamente che gli unici commenti nel codice siano quelli necessari per comprendere il codice stesso: lo scopo, la logica aziendale e casi eccezionali. Lasciare la documentazione relativa al set di modifiche al sistema di controllo della versione. Se non stai usando un VCS, inizia ora. Esistono diversi VCS di alta qualità gratuiti (Subversion, Mercurial, Git, ecc.).

Uso il tempo presente imperativo, quindi qualcosa del tipo:

Cambia "x" in "y"

Questo è raccomandato dagli sviluppatori Git:

• l'organismo dovrebbe fornire un messaggio di commit significativo che:
  • usa l'imperativo, presente: "cambia", non "cambiato" o "cambia".

All'inizio può sembrare un po 'strano, ma se pensi a un commit come a una patch che fa qualcosa, ha più senso. (Ciò è particolarmente vero in un DVCS come Git, in cui si estraggono cambiamenti da altre persone che agiscono sul repository.)

Non importa davvero; Penso che sia stile personale e preferenza. Come per scrivere quasi tutto, sii coerente con te stesso e con altri commenti.

I commenti sul codice dovrebbero essere naturali da leggere.

Se stai leggendo il codice dicendo a te stesso "Questo codice sta facendo X", allora dovresti scrivere il commento al tempo presente, poiché è probabile che anche quello che leggerà il codice in quel momento penserà. Se dall'altro hai pensato a un determinato punto "Questo codice ha fatto X" allora dovrebbe essere passato. Alla fine si riduce alle preferenze personali, a meno che per qualche motivo non si stiano seguendo le linee guida su come commentare il codice (ad es. Per un progetto di gruppo o per una classe, ecc.).

Se stai usando git, la convenzione è usare il presente perché i messaggi di commit generati con gli strumenti git (ad es. Unione) usano il presente.

Dovresti usare il passato.

Il motivo per cui stai rispondendo alla domanda che cosa ha ottenuto questo impegno? Pensalo come dire al tuo VCS cosa hai fatto:

Impegna 123
Modificato XYZ in ABC

Per fornire esempi contrari, l'utilizzo del tempo futuro fa sembrare che stai chiedendo a qualcun altro di farlo:

Impegna 123
Cambia XYZ per fare ABC

e usare il tempo presente suona come se fossi a metà:

Impegna 123
Modifica XYZ per eseguire ABC

Usa il tempo presente: "Cambia X in Y", quasi come se fosse un elemento in un chiaro elenco TODO.

In generale, proprio come una sceneggiatura, evita i verbi come "essere" e "è". Ad esempio, non è "cammina", ma "cammina".

Ma in questo particolare esempio, se stai parlando di commenti in codice e non di commenti in check-in, credo che "Cambia X in Y" sia un commento terribile. Non aggiunge nuove informazioni e, se il codice dovesse cambiare, potrebbe anche essere errato. È meglio se si estrae il codice in un metodo (o in una classe) e si documenta invece quel metodo. Se è abbastanza chiaro, sarà sufficiente solo un buon nome di metodo.

A proposito, per i metodi di documentazione, è possibile utilizzare il tempo futuro, ad esempio: "Se il numero fornito è negativo, absrestituirà l'entità del numero."

I commenti sono (o dovrebbero essere), come qualsiasi cosa scritta, espressioni di qualcosa, e dovrebbero semplicemente seguire le stesse regole nei linguaggi naturali (tenendo conto di abbreviazioni e abbreviazioni specifiche della situazione o artefatto documentato.

I commenti sul tempo presente ( .ie "cambia" o "sta cambiando" ) indicano che un dato di dati gestito dall'algoritmo documentato viene in qualche modo influenzato. Cioè, indica cosa sta facendo il codice o cosa sta succedendo ai dati manipolati.

I commenti al passato dovrebbero indicare un'affermazione, una condizione preliminare o post-condizione di qualcosa che è accaduto prima del punto in cui risiede il commento. Per esempio:

L'input è già stato convalidato prima di inserire questo blocco di codice

o

I dati sono stati scritti su file al termine dell'esecuzione di questo codice

I commenti al passato possono anche spiegare perché si sta facendo qualcosa ( questa funzione fa X e Y per gestire un problema con il database legacy ) .

I commenti al passato che indicano una modifica al codice stesso (.ie. X è stato modificato in Y ) non dovrebbero esistere nel codice. Dovrebbero invece esistere come commenti di revisione nel repository del codice sorgente.

I commenti in futuro dovrebbero indicare una condizione che deve essere soddisfatta o affrontata, ma che per la ragione X o Y non è stata fatta in questo momento. Per esempio:

Quando finalmente migreremo il db, dovremo cambiare questa logica

o

TODO: appena possibile, rivisitare la convalida dell'input: potrebbe non riuscire per il tipo di input X o Y, potrebbe richiedere enormi cambiamenti che non possono essere implementati in questo momento.

Per il successivo tipo di commenti TODO , dovrebbe esistere qualche altra forma di documentazione per assicurarsi che tali cambiamenti abbiano effettivamente luogo. L'ultima cosa che vuoi sono i TODO persi nel tempo e nello spazio: P

Prendilo con un granello di sale, ma in genere quelle sono le regole che di solito seguo quando faccio i miei commenti.

Il commento riguarda la comunicazione agli esseri umani, quindi mentre la coerenza è importante, è importante non impantanarsi nei principi quando i principi stessi ostacolano una buona comunicazione. Detto questo, utilizzo i seguenti pseudo-standard:

• I commenti che descrivono un comportamento desiderato assumono la forma di una frase imperativa presente.

  // Calculate the width of the curve at x height.
  

• Utilizza una serie di parole chiave in maiuscolo per descrivere temi comuni nella codifica (e per semplificare la ricerca):

  // NOTE: <This code was written this way for a reason.>
  // TODO: <This code is incomplete. Finish it.>
  // HACK: <This code was written this way for a reason that you won't like.>
  // FIXME: <This code has a known flaw. Fix it.>