Ogni volta che scrivo un tipico costrutto if-else in qualsiasi lingua, mi chiedo quale sarebbe il modo migliore (in termini di leggibilità e panoramica) per aggiungere commenti ad esso. Soprattutto quando si commenta la clausola else, i commenti mi sembrano sempre fuori luogo. Supponiamo che abbiamo un costrutto come questo (gli esempi sono scritti in PHP):

if ($big == true) {
    bigMagic();
} else {
    smallMagic()
}

Potrei commentarlo in questo modo:

// check, what kind of magic should happen
if ($big == true) {
    // do some big magic stuff
    bigMagic();
} else {
    // small magic is enough
    smallMagic()
}

o

// check, what kind of magic should happen
// do some big magic stuff
if ($big == true) {
    bigMagic();
}
// small magic is enough
else {
   smallMagic()
}

o

// check, what kind of magic should happen
// if:   do some big magic stuff
// else: small magic is enough
if ($big == true) {
    bigMagic();
} else {
    smallMagic()
}

Quali sono i tuoi esempi di best practice per commentare questo?

Preferisco:

if ($magic == big) {
    bigMagic();
}
else {
    smallMagic();
}

o:

if ($magic == big) {
    // big magic requires a big surprise, so I'm telling you about it here
    surprisingThing();
}
else {
    // give a magical feeling even if $magic is noMagicAtAll
    smallMagic();
}

Sembra un po 'sciocco scrivere un commento che spieghi cosa controlla la tua condizione a meno che il codice non lo indichi chiaramente. Anche allora, è meglio riscrivere il codice per renderlo il più chiaro possibile. Lo stesso vale per i corpi dei blocchi condizionali: se puoi rendere evidente la ragione per fare qualcosa di ovvio, fallo invece di commentare.

Non sottoscrivo la filosofia "non scrivere mai commenti", ma credo nell'evitare i commenti che dicono ciò che il codice dovrebbe dire. Se scrivi un commento come "controlla che tipo di magia dovrebbe accadere" quando il codice potrebbe dire if ($magic == big) {..., i lettori smetteranno di leggere i tuoi commenti molto rapidamente. L'uso di un numero inferiore di commenti più significativi conferisce maggior valore a ciascuno dei tuoi commenti e i lettori hanno maggiori probabilità di prestare attenzione a quelli che scrivi.

È importante scegliere nomi significativi per le variabili e le funzioni. Un nome ben scelto può eliminare la necessità di commenti esplicativi in ​​tutto il codice. Nel tuo esempio, $magico forse $kindOfMagicsembra un nome migliore rispetto a $bigquando, secondo il tuo esempio, è il "tipo di magia" che viene testato, non la "grandezza" di qualcosa.

Dì più che puoi nel codice. Salva la prosa per i casi che richiedono più spiegazioni di quelle che puoi ragionevolmente scrivere nel codice.

Prova i nomi delle variabili esplicative

I commenti possono essere fantastici, ma quando possibile, rendere il codice auto-documentante. Un modo per farlo è con nomi di variabili esplicativi. Ad esempio, piuttosto che questo:

if (user.has_sideburns && user.can_gyrate) {
  // This user is a potential Elvis impersonator

}

Preferirei una variabile con nome:

is_potential_elvis_impersonator = user.has_sideburns && user.can_gyrate

if (is_potential_elvis_impersonator) {
  ...
}

Solo per completare alcuni commenti:

L'uso corretto dei commenti è per compensare la nostra incapacità di esprimerci nel codice. Nota che ho usato la parola fallimento. È ciò che intendevo. I commenti sono sempre errori. Dobbiamo averli perché non possiamo sempre capire come esprimerci senza di loro, ma il loro uso non è motivo di celebrazione. ( Codice pulito di Robert C. Martin )

A proposito: raccomando questo libro.

I commenti non devono parafrasare il codice ma spiegano cose che non sono nel codice (immagine più grande, perché, perché non è stata scelta un'alternativa ...) E i tuoi commenti di esempio sono proprio questi: parafrasi del codice.

A volte potresti sentire che è necessaria una parafrasi all'inizio del elseramo, ma questo è spesso un segno che il tuo thenramo è troppo grande.

Nel tuo esempio specifico, probabilmente i commenti non sono necessari. Come accennato da Caleb , se il codice è chiaramente scritto e le variabili hanno nomi semantici, se è meno probabile che le dichiarazioni necessitino di commenti.

Confronta il tuo snippet con questo:

if ($x) {
    func1();
} else {
    func2();
}

In questo caso, vorrai sicuramente usare i commenti per descrivere cosa rappresentano x, func1 e func2 (e schiaffeggiare la persona che ha nominato le cose con quello schema, specialmente se sei stato tu). Non puoi nemmeno dire se $xdovrebbe essere un booleano. Ma anche questo è un caso in cui non hai necessariamente bisogno di commenti, se sei in grado di riformattare e rinominare.

In generale, mi piace scrivere commenti per blocchi logici che descrivono cose che il codice non può da solo. Un one-liner ogni ~ 10-20 righe che descrive ciò che la seguente manciata di righe compie a un livello superiore di astrazione (ad esempio // Make the right amount of magic happenper il tuo esempio) ti aiuterà a orientarti e a dare a un nuovo revisore informazioni su ciò che stai facendo e quando .

In realtà spesso scrivo queste righe singole prima di iniziare a scrivere codice, in modo da non perdere traccia del flusso che il segmento dovrebbe avere.

Infine, se preferisci davvero (o c'è un mandato che richiede) clausole di commento in un blocco if indipendentemente dalla leggibilità del codice, ti consiglio di:

// Broad description of block
if (something) {
    //Do this because something
    something();
} else {
    //Do this because !something
    somethingElse();
}

Penso che sia il più pulito, perché il commento si allinea al codice a cui appartiene. Un commento che descriva quale codice fa dovrebbe essere il più vicino possibile al commento che descrive.

if (IsWeekDay(day))
{// weekday -> alarm at 7am
   ...
}
else if(day == DayOfWeek.Saturday)
{// saturday -> alarm at 11am
   ...
}
else
{// (sunday) -> no alarm
   ...
}

Tengo le staffe allineate e le metto subito dopo la parentesi.

[Condition] -> [pseudo-code]

D'altra parte, tecnicamente significa che tutte le altre condizioni sono fallite, quindi di solito uso le parentesi.

([Condition]) -> [pseudo-code]

Nota: questo è per C #.

Cerco di usare i commenti all'interno del blocco dicendo ciò che fa quel blocco (il tuo primo campione).

Dove questo tipo di guasto si interrompe è quando si utilizza elseif. Uso Basic quindi non esiste un blocco finale esplicito e spesso devo commentare quale condizione sta controllando che va sulla riga sopra (con un'interruzione di linea ovviamente) se è troppo lunga.

'Check XYZ
If Condition1 then
  'We need to do T and S
  DoCodeFor1();

'Check ABC
ElseIf Condition1 then
  'This requires something else to be done
  DoCodeFor2()

Else
  'We have no other option than to...
  DoCodeFor3()

End If

• Mantieni i tuoi blocchi condizionali davvero brevi.
• Chiama un metodo con un bel nome descrittivo se sembra che il tuo codice condizionale sarà più di una semplice linea o due.
• Usa dei bei nomi descrittivi per le tue variabili.
• Assicurati che la frase condizionale sia chiara nel suo significato e non offuscata o lunga. Utilizzare un metodo se aiuta a mantenere le cose pulite e leggibili.

Se tutto quanto sopra fallisce, aggiungi un commento descrittivo molto piccolo prima dell'istruzione if, per chiarire il tuo intento. Altrimenti, non dovrebbe esserci la necessità di commentare affatto.

In C ++ o C # in genere non commenterei casi semplici (quando è chiaro cosa sta succedendo), e utilizzare questo tipo di stile per commentare il resto finale ...

if (pattern == AAA)
{
  DoSomethingAAA();
}
else if (pattern == BBB)
{
  DoSomethingBBB();
}
else // if (pattern == CCC)
{
  DoSomethingCCC();
}