Esistono studi empirici sugli effetti del commentare il codice sorgente sulla qualità del software, sulla manutenibilità e sulla produttività degli sviluppatori? [chiuso]

Sono un sostenitore del commento sul codice sorgente e della documentazione dei prodotti software. È la mia esperienza personale e l'osservazione che lavorare sul codice sorgente che è rigorosamente commentato mi ha aiutato in diversi modi quando ho dovuto sviluppare software o mantenerlo.

Tuttavia c'è un altro campo che dice che commentare è in definitiva inutile o il suo valore è discutibile. Numerosi sostenitori della codifica senza commentare sostengono che:

Se un pezzo di codice è ben scritto, è autoesplicativo e quindi non necessita di commenti
Se un pezzo di codice non è autoesplicativo, quindi riformattalo e rendilo autoesplicativo in modo che non abbia bisogno di commenti
La tua suite di test è la tua documentazione live
Col passare del tempo il codice e i commenti si sincronizzano e diventa un'altra fonte di mal di testa
Agile afferma che il codice di lavoro è più importante delle pile di documentazione, quindi possiamo tranquillamente ignorare la scrittura di commenti

Per me questo è solo 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 notevole quantità di codice che non si spiega da sé.

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 sui pro e contro della documentazione e sui 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 commentando il codice sorgente, sulla sua qualità e manutenibilità, nonché i suoi effetti sulla produttività del team.

Ti sei imbattuto in tali articoli e qual è stato il loro esito, se ce ne sono stati?

— Behrang Saeedzadeh
fonte

Penso che questa sia comunque una domanda interessante, ma non mi sorprende molto che possa chiudersi qui. Ecco perché l'ho pubblicato anche su Quora.

— Behrang Saeedzadeh,

@gnat - Mi sembra che "Quali ricerche sono state fatte in questo aspetto del campo dello sviluppo del software?" è una domanda piuttosto diversa rispetto alle richieste "per favore dammi libri su un argomento" che non sono del tutto benvenute.

— Josh Kelley,

Solo dalla lettura del titolo: Non ci sono studi empirici sugli effetti di qualcosa sulla qualità. Se ci fosse, questo sito non esisterebbe.

— Euforico,

@Euforiche le tue due affermazioni si contraddicono a vicenda. Se ignoriamo il "folle" documento di 30 anni, non c'è conflitto. Tuttavia, non dovremmo ignorare i risultati solo perché sono vecchi, ma valutare criticamente il modo in cui si collegano al lavoro moderno (come dovremmo anche con i nuovi risultati).

@Euforico Vorrei che lo pubblicassi come una risposta, in modo da poter sottovalutare la tua totale mancanza di ricerca nella tua affermazione generale. Ci sono tonnellate di articoli e ricerche, empiriche e non, sugli effetti di diverse tecniche sulla qualità del software. Hai studiato qualcosa sull'ingegneria del software?

— Andres F.

In "L'effetto della modularizzazione e dei commenti sulla comprensione del programma" (1981), Woodfield, Dunsmore e Shen hanno scoperto che "i soggetti i cui programmi contenevano commenti erano in grado di rispondere a più domande di quelle senza commenti".

Tuttavia, in "Imparare una metrica per la leggibilità del codice" (2010), Raymond PL Buse e Westley Weimer hanno scoperto che i commenti hanno solo un effetto limitato sulla leggibilità e sulla qualità:

Dall'abstract:

Costruiamo una misura di leggibilità automatizzata e ... dimostriamo che questa metrica è fortemente correlata a tre misure di qualità del software: modifiche al codice, rapporti sui difetti automatizzati e messaggi di registro dei difetti ... I nostri dati suggeriscono che i commenti, di per sé, sono meno importanti di semplici righe vuote a giudizi locali di leggibilità.

Da pagina 12:

Abbiamo scoperto che i commenti erano solo moderatamente ben correlati con la nozione di leggibilità dei nostri annotatori (potenza relativa del 33%). Una conclusione potrebbe essere che, sebbene i commenti possano migliorare la leggibilità, vengono generalmente utilizzati in segmenti di codice che sono iniziati in modo meno leggibile: il commento e il codice illeggibile si bilanciano efficacemente. L'effetto netto sembrerebbe essere che i commenti non sono sempre, di per sé, indicativi di alta o bassa leggibilità.

Tieni presente che i sostenitori della "codifica senza commentare" non stanno dicendo che il codice senza commenti è meglio del codice con commenti. Stanno sostenendo che un particolare stile di codice senza commenti - uno che estrae il codice in metodi con nomi auto-descrittivi, uno che introduce spiegando le variabili , uno che ha una buona suite di test - è meglio del codice che non fa quelle cose ma ha commenti. Ciò potrebbe complicare l'applicabilità di tutti gli studi che sono stati condotti.

— Josh Kelley
fonte

Il documento di Woodfield et al. Parla di una particolare varietà di commenti, approssimativamente equivalente a quello che ora si chiamerebbe Javadoc: "Nello specifico, questa ricerca tenta di determinare se brevi commenti, inseriti appena prima di un modulo logico, possono aiutare la comprensione descrivendo brevemente la funzione del modulo logico e aiuta a definire i confini del modulo logico. "

Avrei dovuto aggiungere all'epoca: questo non vuol dire che non ha valore, anzi è uno studio interessante e ben costruito. Ho solo pensato che bisognava dire che non stavano prendendo in considerazione tutti i commenti.