Al mio primo vero lavoro sono stato assunto da un paio di OCDers che volevano che scrivessi sempre codice come questo:
/* comment describing what the next few lines do */
a line of code
a line of code
a line of code
/* comment describing what the next few lines do */
a line of code
a line of code
a line of code
ecc.
L'idea era che dovrebbe essere possibile ottenere una comprensione relativamente buona di ciò che fa il codice leggendo i commenti, ignorando completamente il codice reale. Perché ciò funzioni, c'erano alcune regole aggiuntive, ad esempio che i commenti sul codice dovevano sempre iniziare con un verbo, ecc.
Quindi, ho imparato a programmare in questo modo, e ho pensato che fosse bello. Sfortunatamente, questo ha portato a molte situazioni WTF, come la seguente:
function int foo( int x )
{
/* preconditions */
assert x > 0;
/* change state */
this.x = x;
/* return same value to enable fluent style */
return x;
}
Ai lavori che ho fatto dopo, la gente ha guardato il mio stile di codifica e non ha detto nulla per evitare di insultarmi, o, se si sentivano abbastanza amichevoli da darmi dei consigli, mi hanno detto che questo stile di commento era deficiente .
Inoltre, altri programmatori non si sono sentiti in alcun modo obbligati a seguire il mio modo di commentare, quindi quando qualcun altro ha modificato il mio codice, il loro totale disprezzo nei confronti dei miei commenti era spesso equivalente a sovversione, ad esempio:
/* return same value to enable fluent style */
notifyTheWorldThatXHasChanged();
return x;
Quindi, nella mia esperienza, nella maggior parte dei luoghi di lavoro là fuori, questo stile di commenti tende a essere disapprovato.
Il mio consiglio sarebbe quello di scrivere un codice di auto-documentazione e seguire la regola "commenti minimi", il che significa solo aggiungere un commento se è necessario. I commenti nel codice dovrebbero essere necessari solo in circostanze eccezionali e la loro presenza dovrebbe avvertire il lettore che sta succedendo qualcosa di straordinario.
Quando è necessario un commento? Quando una lettura ragionevolmente attenta del codice non rivela ciò che fa il codice, o perché una determinata cosa viene eseguita in un modo particolare.
Cosa dovrebbe essere considerato una lettura del codice ragionevolmente attenta? È quando focalizzi tutta la tua attenzione sulla lettura del codice, con un sincero obiettivo di capire cosa lo fa, ma tu credi che il codice faccia effettivamente quello che sembra mirare a fare, quindi in realtà non stai attraversando il dolore di eseguire il codice nella tua mente, cercando di capire cosa veramente fa, come se il codice avesse secondi fini . Dovresti farlo solo quando esegui il debug del codice.
Ovviamente, il trucco è scrivere quel codice elusivo di auto-documentazione che, quando lo guardi, diventa immediatamente ovvio. Mi piace credere che quello che facciamo sia per lo più una scienza, ma questo particolare piccolo sembra più un'arte per me. Un'arte che vale la pena di padroneggiare.