Preferisco entrambi:

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 spiega quali sono le tue condizioni, a meno che il codice non lo indichi chiaramente. Anche in questo caso, è meglio riscrivere il codice per renderlo il più chiaro possibile. Lo stesso vale per i corpi dei blocchi condizionali: se riesci a fare la ragione per fare qualcosa di ovvio, fallo invece di commentare.

Non sottoscrivo la filosofia del "non scrivere mai commenti", ma credo di evitare commenti che dicano che cosa dovrebbe dire il codice. 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 velocemente. L'utilizzo di un numero minore di commenti più significativi conferisce a ciascuno dei tuoi commenti più valore e i lettori hanno maggiori probabilità di prestare attenzione a quelli che scrivi.

La scelta di nomi significativi per le variabili e le funzioni è importante. Un nome ben scelto può eliminare la necessità di commenti esplicativi in tutto il codice. Nel tuo esempio, $magic o forse $kindOfMagic sembra un nome migliore di $big poiché, secondo il tuo esempio, è il "tipo di magia" che viene testato, non la "grandezza" di qualcosa.

Dì il più possibile in codice. Salva la prosa per i casi che richiedono più spiegazioni di quanto tu possa ragionevolmente scrivere nel codice.

Prova i nomi delle variabili esplicative

I commenti possono essere grandiosi, ma quando possibile, rendi il codice auto-documentante. Un modo per farlo è con i nomi delle variabili esplicative. Ad esempio, piuttosto che questo:

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

}

Preferirei una variabile denominata:

is_potential_elvis_impersonator = user.has_sideburns && user.can_gyrate

if (is_potential_elvis_impersonator) {
  ...
}

Solo per completare alcuni commenti:

The proper use of comments is to compensate for our failure to express ourself in code. Note that I used the word failure. I meant it. Comments are always failures. We must have them because we cannot always figure out how to express ourselves without them, but their use is not a cause for celebration. (Clean Code by Robert C. Martin)

BTW: Raccomando questo libro.

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

A volte potresti sentire che una parafrasi è necessaria all'inizio del ramo else , ma spesso è un segnale che il tuo ramo then è troppo grande.

Nel tuo esempio specifico, i commenti probabilmente non sono necessari. Come Caleb menzionato , se il codice è scritto in modo chiaro e le variabili hanno nomi semantici, se le dichiarazioni hanno meno probabilità di dover commentare .

Confronta lo snippet con questo:

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

In questo caso, vorresti sicuramente usare i commenti per descrivere cosa x, func1 e func2 rappresentano (e dare uno schiaffo alla persona che ha chiamato le cose con quello schema, specialmente se fossi tu). Non puoi nemmeno dire se $x dovrebbe essere un booleano. Ma anche questo è un caso in cui non hai necessariamente bisogno di commenti, se sei in grado di refactoring 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 serie di linee realizza ad un livello più alto di astrazione (ad esempio // Make the right amount of magic happen per il tuo esempio) ti aiuterà a mantenere l'orientamento e a dare una nuova visione di ciò che sei facendo e quando.

In realtà scrivo spesso questi one-liners in prima inizio a scrivere codice, in modo da non perdere traccia del flusso che il segmento dovrebbe avere.

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

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

Sento che è il più pulito, perché il commento si allinea con il codice a cui appartiene. Un commento che descrive quale codice 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 la metto subito dopo la parentesi.

[Condition] -> [pseudo-code]

Su un altro, tecnicamente significa che tutte le altre condizioni non sono riuscite, quindi di solito uso le parentesi.

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

Nota: questo è per C #.

Cerco di usare commenti all'interno del blocco dicendo cosa fa quel blocco (il tuo primo campione).

Dove questo tipo "si rompe è quando si usa elseif . Io uso Basic, quindi non esiste un blocco finale esplicito e spesso devo commentare quale controllo sta verificando la condizione che segue la riga sopra (con un'interruzione di riga, 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 riga o due.
• Utilizza nomi descrittivi piacevoli per le tue variabili.
• Assicurati che l'istruzione condizionale sia chiara nel suo significato e non offuscata o lunga. Usa un metodo se aiuta a mantenere le cose pulite e leggibili.

Se tutto quanto sopra non riesce, aggiungi un commento descrittivo molto piccolo prima dell'istruzione if, per chiarire il tuo intento. Altrimenti, non ci dovrebbe essere assolutamente bisogno di commentare.

In C ++ o C # di solito non commenterei casi semplici (quando è chiaro cosa sta succedendo), e uso questo tipo di stile per commentare l'ultimo ...

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