Vorrei iniziare la mia risposta con una citazione fatta da Jeff Atwood nel suo post sul blog Il codice ti dice come, i commenti ti dicono perché :
the best kind of comments are the ones you don't need
Dichiara anche che:
You should first strive to make your code as simple as possible to understand without relying on comments as a crutch. Only at the point where the code cannot be made easier to understand should you begin to add comments.
Sono assolutamente d'accordo e a questo punto devo aggiungere che prima di poter iniziare a rendere il codice il più semplice possibile, faccio in modo che il codice funzioni e poi inizi a rifattorizzare. Quindi durante la prima corsa prima di refactoring aggiungere perché i commenti aiutano molto.
Ad esempio se si utilizzano 3 cicli nidificati con 2 hash dimensionali per riempire una tabella dei giorni feriali mentre si analizzano i dati, è molto facile perdere traccia di ciò che è stato fatto da qualcuno o anche da soli se non è stato guardato per alcune settimane e improvvisamente refactoring .
[loop1]6oclock -> [loop2]Monday -> [loop3]stage 1 to 4
-> tuesday-> stage 1 to 4
...
-> Saturday -> stage 1 to 4
7oclock -> Monday-> stage 1 to 4
....etc.
La tomaia è un esempio di come funzionano 3 cicli annidati prima del refactoring.
Inoltre, la spiegazione di alcune condizioni del ramo può aiutare a capire il codice molto meglio con ciò che si stava pensando nel processo:
// added a zero before the actual day in order for the days always to be 2 digits long.
if( actualDayFuture < 10 )
{
actualDayFuture = padIfSingleDigitDate(actualDayFuture);
}
Anche il codice semplice e ovvio funziona bene con i commenti. Solo per rendere le cose un po 'più ovvie, più chiare o più facili da capire per i colleghi e anche per te stesso nel mantenimento del software.
Certo che xp afferma di avere un codice che si spiega da sé, ma fa male un commento su una riga?
Trovo anche le seguenti regole da questo blog essere molto utile:
- Understand the material before you write
- Write as though your audience is a fourth grader
- Think about how readers might misinterpret you
Chiunque debba tornare nel proprio codice o in qualcun altro o addirittura in un codice legacy sa che può essere un mal di testa. Quindi, invece di essere pigri o cercare di essere un uber-coder nel non commentare nulla o molto poco, perché non creare il proprio o un bugger povero, che deve mantenere il proprio codice, la vita futura è molto più facile seguendo le regole citate.
Anche molte descrizioni di programmazione fatte sono messe in dubbio durante le recensioni e non è sempre chiaro il motivo per cui alcune parti sono state scritte come erano anche se alcune sezioni di codice sono vitali per un programma per funzionare a causa di un grosso bug trovato mentre il codice era usato negli anni. Quindi, per non annoiarvi completamente con un tl; dr close con un'ultima citazione da acmqueue :
Prior, clear, and extensive documentation is a key element in creating software that can survive and adapt. Documenting to high standards will decrease development time, result in better work, and improve the bottom line. It’s hard to ask for more than that from any technique.