Sappiamo tutti che le revisioni del codice sono generalmente una buona pratica , ma che dire della revisione della documentazione? Molti sviluppatori con cui collaboro pubblicheranno pagine wiki, javadoc, ecc. Ma la maggior parte delle volte, a meno che qualcun altro non ne abbia bisogno, i documenti passeranno inosservati e non verificati.
Esistono buoni strumenti o metodologie per la peer reviewing della documentazione del codice?
In realtà, penso che il tuo post contiene due domande diverse, iniziamo con quella semplice:
are there any good tools or methodologies for peer reviewing code documentation?
Non penso che esistano "strumenti o metodologie speciali", perché non è necessario nulla di speciale. La documentazione peer reviewing funziona come qualsiasi altro tipo di correzione di bozze: dai al lettore i documenti, li legge, aggiunge commenti o suggerimenti per le modifiche e infine discuti i suggerimenti. Questo è tutto, funziona con qualsiasi tipo di tecnologia di documentazione (ovviamente, alcune tecnologie rendono la correzione di bozze e i commenti un po 'più semplici, ma ciò non cambia la metodologia generale).
Many devs that I work with will put up wiki pages, javadocs, etc, but most of the time, unless someone else needs it right away the docs will go unnoticed and unreviewed.
Questa è in realtà la tua seconda domanda - in altre parole "perché molte persone non prendono nota della documentazione del codice separata o non si preoccupano della loro qualità?"
Penso che questa domanda sia stata discussa in modo approfondito qui su questo sito, così come in molti altri posti. È una domanda molto ampia, ma tutto si riduce a "la documentazione aggiuntiva vale davvero la pena?" E fintanto che la risposta non è chiaramente "sì", non aspettarti di ottenere una risposta diversa a "" vale davvero la pena di esaminarla? "
La mia opinione personale su questo è che ogni team responsabile di un determinato prodotto deve trovare la quantità di documentazione e il livello di astrazione corretto per la documentazione che funziona per il team e il prodotto . E una volta che l'hai trovato, e il team vede molto valore in quei documenti, la domanda di recensioni si presenterà da sola.
Dato che qualsiasi prodotto di qualità richiede documentazione, anche se è un documento di avvio che dovresti creare, aggiornare e revisionare i documenti.
I problemi arrivano quando è difficile accedere alla documentazione, quindi se devi controllare un documento word da Sharepoint, modificalo e poi caricarlo di nuovo, non troverai molte persone che desiderano apportare le modifiche. Quindi trovo la cosa migliore se si presuppone che la documentazione sia parte del codice sorgente e se si mettono le fonti del documento accanto al codice non ci sono scuse per non aggiornarlo, ad esempio se la documentazione è costituita da file di testo in un linguaggio di markup, quindi le modifiche del doc sono facile come modificare un grande commento. Il tuo sistema CI può trasformare tali sorgenti in Word o PDF o HTML, in modo da avere sempre una documentazione aggiornata che è sia facile da modificare e facile da recensire (basta controllare la differenza della cronologia scm).
Le pagine wiki sono meno facili in quanto non corrispondono strettamente alla cronologia SCM, ma hai ancora la cronologia che puoi controllare, l'editor dovrà dire quali pagine hanno cambiato.
Oltre a questo, non ci sono tooling per la revisione della documentazione di Word che è una cosa buona (devi ancora andare manualmente e leggere il tutto per vedere se è corretto) così alla fine devi dover aggiungere un commento di revisione che tu aggiornato i documenti nella sezione X, capitolo Y, pagina Z. Ovviamente la risposta a questo è smettere di usare Word.
Leggi altre domande sui tag code-reviews documentation