I commenti dovrebbero essere letti nel loro contesto, quindi:

presente

Per i commenti di origine sopra un metodo o prima che si verifichi qualche 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

function X changed

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 legge in futuro si riferirà all'atto del cambiamento come accaduto in passato.

Formattare qualcosa come "Modifica" implica che al momento si sta effettuando la modifica e che il codice potrebbe non essere terminato.

nota: Personalmente, inserisco solo i commenti di modifica quando si verifica una drastica modifica.

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 utilizzare passato .

Tuttavia, questo tipo di commento è più adatto al tuo sistema di controllo della versione. Il controllo della versione svolge un ruolo molto migliore nel rilevamento delle modifiche rispetto ai commenti manuali. Con i sistemi di controllo della versione, è più appropriato documentare in tempo presente poiché tali commenti si applicano al momento in cui viene commessa la modifica. Ma funzionerà.

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

Uso il tempo presente imperativo, quindi qualcosa del tipo:

Change "x" to be "y"

Questo è raccomandato dagli sviluppatori Git:

• the body should provide a meaningful commit message, which:
  • uses the imperative, present tense: "change", not "changed" or "changes".

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

Non ha molta importanza; Penso che sia lo stile e le preferenze personali. Come per scrivere quasi tutto, solo essere 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 è facendo X" allora dovresti scrivere il commento nel tempo presente poiché è probabile che qualcuno che legge il codice in quel momento sia pensando pure. Se dall'altra parte hai pensato a un particolare punto "Questo codice ha X" allora dovrebbe essere passato. Alla fine si tratta di preferenze personali, a meno che per qualche motivo tu non abbia le linee guida su come commentare il tuo codice (cioè per un progetto di squadra o per una classe, ecc.)

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

Dovresti usare il passato.

La ragione per cui stai rispondendo alla domanda che cosa ha ottenuto questo impegno? Pensa a ciò che dice al tuo VCS che cosa hai fatto:

Commit 123
Changed XYZ to do ABC

Per dare esempi contrari, usare il tempo futuro fa sembrare che stai chiedendo a qualcun altro di farlo:

Commit 123
Change XYZ to do ABC

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

Commit 123
Changing XYZ to do ABC

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

In generale, proprio come in una sceneggiatura, evitare verbi come "essere" e "è". Ad esempio, non è "sta camminando", ma "cammina".

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

A proposito, per documentare i metodi, potresti usare il futuro, ad es .: "Se il numero fornito è negativo, abs restituirà la grandezza del numero."

I commenti sono (o dovrebbero essere), come qualsiasi cosa scritta, espressione di qualcosa, e dovrebbero semplicemente seguire le stesse regole nei linguaggi naturali (tenendo in considerazione le abbreviazioni e le abbreviazioni specifiche della situazione o degli artefatti documentati.

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

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

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

o

I dati sono stati scritti nel file alla fine di questo codice in esecuzione

I commenti al passato possono anche spiegare perché qualcosa è stato fatto ( questa funzione fa X e Y per affrontare un problema con il database precedente. )

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 X o Y la ragione non viene attualmente eseguita. Ad esempio:

Quando finalmente migriamo il db, dovremo cambiare questa logica

o

TODO: al più presto, rivisitare la convalida dell'input - potrebbe fallire 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 è TODO persa nel tempo e nello spazio: P

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

I commenti riguardano la comunicazione con gli esseri umani, quindi, mentre la coerenza è importante, è importante non rimanere impantanati nei principi quando i principi stessi intralciano una buona comunicazione. Detto questo, io uso i seguenti pseudo-standard:

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

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

• Utilizza un insieme di parole chiave tutte maiuscole 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.>