Sono un sostenitore di commentare il codice sorgente e documentare i prodotti software. È mia personale esperienza e osservazione che lavorare su un codice sorgente rigorosamente commentato mi ha aiutato in diversi modi quando ho dovuto sviluppare software o mantenerlo.
Tuttavia c'è un altro campo in cui il commento è in definitiva privo di valore o il suo valore è discutibile. Numerosi sostenitori della codifica senza commenti sostengono che:
- Se una parte di codice è ben scritta, è auto-esplicativa e quindi non ha bisogno di commenti
- Se una parte di codice non è auto-esplicativa, quindi la si rifatta e la rende auto-esplicativa in modo che non abbia bisogno di commenti
- La tua suite di test è la tua documentazione live
- Il codice temporale e i commenti non sono sincronizzati e diventa un'altra fonte di mal di testa
- Agile dice che il codice di lavoro è più importante delle pile di documentazione, quindi possiamo tranquillamente ignorare i commenti scritti
Per me questo è solo un dogma. Ancora una volta, la mia osservazione personale è stata che il software scritto da team di sviluppatori intelligenti ed esperti alla fine finisce con una quantità considerevole di codice che non è auto-esplicativo.
Ancora una volta, l'API Java, l'API Cocoa, l'API Android, ecc. mostrano che se si desidera scrivere e conservare documentazione di qualità, è possibile.
Detto questo, le conversazioni su pro e contro della documentazione e commenti sul codice sorgente basati su convinzioni personali di solito non finiscono bene e non portano a conclusioni soddisfacenti.
In quanto tale, sto cercando documenti accademici e studi empirici sugli effetti della documentazione del software, in particolare sulla creazione di commenti sul codice sorgente, sulla sua qualità e manutenibilità e sui suoi effetti sulla produttività del team.
Sei incappato in questi articoli e quale è stato il loro esito, se ce ne sono stati?