Le azioni / i metodi dovrebbero essere coniugati nei commenti?

Se hai qualche dubbio su come nominare e documentare, guarda come gli sviluppatori principali lo fanno. Puoi trovare buoni esempi nella documentazione ufficiale per diversi strumenti, librerie, framework, lingue ecc.

Ad esempio,

• MSDN Stack di <T> documentazione
• PHP.net documentazione mysqli :: ping

La descrizione dei metodi contiene forme coniugate come "Specifi es ", "Ritorno s ", "Remov es " o "Determin es ", mentre i commenti nei metodi utilizzano forme imperative:" verifica connessione "," verifica se il server è attivo "," chiudi connessione "," Crea una copia dello stack ".

Quindi scriverei il tuo codice in questo modo:

// Returns hello
function greeting()
{
  return "Hello";
}

// Starts foo-ing
function foo()
{
   // Show greeting message
   greeting();
}

UPD: E questo ha senso, perché i commenti prima di funzioni e metodi ci dicono cosa fanno le funzioni:

• Foo() restituisce lo stato
• Bar() controlla il valore

mentre i commenti nelle funzioni ci mostrano i passi dell'algoritmo:

• Ottieni lo stato
• Controlla il valore
• Inizia il modulo

La coniugazione è molto rudimentale in inglese, direi che non fa molta differenza. Potrebbe anche essere l'imperativo, in particolare se il metodo è un comando nel contesto della separazione tra query e comandi. Personalmente, è così che l'ho letto, perché in slovacco, la mia lingua madre, i pulsanti sono comunemente etichettati con l'imperativo (che è morfologicamente chiaramente distinto dall'infinito in quella lingua).

// Find the first entry (implicit "onward, contraption, find me the first entry!")

function findFirst(array)
{
   return array[0];
}

Tuttavia, se il nome del metodo è scelto bene, non è necessario riformularlo come frase. Invece documentate gli effetti collaterali, l'uso e cosa no, nel qual caso l'imperativo è inadeguato e si userebbe la 3a persona indicativa. Ovviamente le persone avranno dozzine di opinioni diverse su di esse e alcune daranno inizio a guerre di religione. Idealmente puoi permettere a qualcun altro di rivedere il codice e se capiscono cosa fa un metodo basato sul suo nome + documentazione, allora hai fatto bene, altrimenti no. Ulteriori distinzioni rasentano il ciclismo.

Solo un esempio di un metodo non abbastanza ben definito:

function greeting()
{
   return "Hello";
}

Il nome in sé lascia aperte più opzioni. Questo effettivamente esegue il saluto? O mi dà un valore adatto per salutare gli altri?

Se viene eseguito il saluto stesso, allora chiamerei greet (o performGreeting se non è disponibile un verbo adatto o il verbo è ambiguo) e altrimenti makeGreeting (o produceGreeting o provideGreeting o somesuch ).

Sfortunatamente, non esiste una regola reale che indichi ciò che stai chiedendo.

Personalmente, i miei comportamenti dei commenti dipendono dal linguaggio di programmazione con cui sto codificando. Come sviluppo ad esempio in Python, posso mostrare che la tua prima opzione ( return ) è piuttosto favorita in questo linguaggio di programmazione: Se controlli PEP 0008 e leggi i paragrafi di tutti i commenti, vedrai che preferiamo usare la tua prima opzione:

x = x + 1 # Increment

x = x + 1 # Compensate for border

"""Return a foobang

Optional plotz says to frobnicate the bizbaz first. """

Non farei nessuno dei due. Il tipo di commenti che stai descrivendo sono semplicemente lì per descrivere quali metodi malvagi stanno facendo. Sono rumori.

Invece di chiamare un metodo findFirst e poi avere un commento che descrive cosa significa findFirst , chiama il metodo findFirstEntry e rimuovi il commento.

Lo scopo del codice ben scritto è di dire agli altri sviluppatori (e al compilatore) cosa fa quel codice. Se ulteriori spiegazioni sul perché lo fa in un certo modo, o su come un pezzo di codice necessariamente complicato funziona, quindi aggiungere commenti chiaramente scritti. Se il codice è chiaro, non ingombrarlo con commenti inutili che ripetono semplicemente il codice.