Come semplificare la comprensione di una base di codice di grandi dimensioni

Supponiamo che stia sviluppando un progetto relativamente grande. Ho già documentato tutte le mie classi e funzioni con Doxygen, tuttavia, ho avuto l'idea di mettere un "note del programmatore" su ogni file di codice sorgente.

L'idea alla base è quella di spiegare in parole povere come funziona una classe specifica (e non solo perché come fanno molti commenti). In altre parole, per dare agli altri programmatori una visione diversa di come funziona una classe.

Per esempio:

/*
 * PROGRAMMER'S NOTES:
 *
 * As stated in the documentation, the GamepadManager class 
 * reads joystick joystick input using SDL and 'parses' SDL events to
 * Qt signals.
 *
 * Most of the code here is about goofing around the joystick mappings.
 * We want to avoid having different joystick behaviours between
 * operating systems to have a more integrated user experience, since
 * we don't want team members to have a bad surprise while
 * driving their robots with different laptops.
 *
 * Unfortunately, we cannot use SDL's GamepadAPI because the robots
 * are interested in getting the button/axes numbers, not the "A" or
 * "X" button.
 *
 * To get around this issue, we created a INI file for the most common 
 * controllers that maps each joystick button/axis to the "standard" 
 * buttons and axes used by most teams. 
 *
 * We choose to use INI files because we can safely use QSettings
 * to read its values and we don't have to worry about having to use
 * third-party tools to read other formats.
 */

Sarebbe un buon modo per rendere più semplice un grande progetto per i nuovi programmatori / collaboratori per capire come funziona? Oltre a mantenere uno stile di codifica coerente e un'organizzazione di directory "standard", ci sono "standard" o raccomandazioni per questi casi?

Questo e spettacolare. Vorrei che più sviluppatori di software si prendessero il tempo e gli sforzi per farlo. It:

• Dichiara in parole povere cosa fa la classe (cioè la sua responsabilità),
• Fornisce utili informazioni supplementari sul codice senza ripetere testualmente ciò che il codice dice già,
• Delinea alcune delle decisioni di progettazione e perché sono state prese, e
• Evidenzia alcuni dei gotcha che potrebbero accadere alla prossima persona che legge il tuo codice.

Purtroppo, molti programmatori cadono nel campo di "se il codice è scritto correttamente, non dovrebbe essere documentato". Non vero. Esistono molte relazioni implicite tra classi di codice, metodi, moduli e altri artefatti che non sono evidenti dalla sola lettura del codice stesso.

Un programmatore esperto può creare con cura un design con un'architettura chiara e facilmente comprensibile che è ovvio senza documentazione. Ma quanti programmi del genere hai effettivamente visto?

La chiave per lavorare con un codebase di grandi dimensioni non è dover leggere l'intero codebase per apportare una modifica. Per consentire a un programmatore di trovare rapidamente il codice che sta cercando, il codice dovrebbe essere organizzato e l'organizzazione apparente. Cioè, ogni unità logica nel codice, dall'eseguibile, dalla libreria, dallo spazio dei nomi, fino alla singola classe dovrebbe avere una chiara responsabilità. Vorrei quindi non solo documentare i file di origine, ma anche le directory in cui risiedono.

Le note del programmatore forniscono anche informazioni sulle decisioni di progettazione. Sebbene queste possano essere informazioni preziose, le separerei dalla dichiarazione di responsabilità (per consentire al lettore di scegliere se desidera leggere le responsabilità della classe o la sua logica progettuale) e spostarla il più vicino possibile alla fonte che descrive per quanto possibile, per massimizzare la possibilità che la documentazione venga aggiornata quando il codice è (la documentazione è utile solo se possiamo fidarci della sua precisione - la documentazione obsoleta può essere peggiore di niente!).

Detto questo, la documentazione dovrebbe rimanere ASCIUTTA, ovvero non ripetere le informazioni che avrebbero potuto essere espresse in codice o che erano già state descritte altrove (frasi come "come indicato nella documentazione" sono un segnale di avvertimento). In particolare, i futuri manutentori saranno solo abili nel linguaggio di programmazione del progetto in quanto sono in inglese; parafrasando l'implementazione nei commenti (che vedo del tutto troppo spesso quando le persone sono orgogliose della loro documentazione) non ha alcun vantaggio e probabilmente divergerà dall'implementazione, in particolare se la documentazione non è vicina al codice che descrive.

Infine, la struttura della documentazione dovrebbe essere standardizzata in tutto il progetto in modo che tutti possano trovarla (è un casino reale di documenti di Peter nel tracker dei bug, Sue nel wiki, Alan nel readme e John nel codice sorgente ...) .

Non sarei d'accordo che questo sia un ottimo approccio, principalmente dovuto a

1. Quando si esegue il refactoring del progetto, si spostano i metodi, la documentazione si interrompe.

2. Se la documentazione non viene aggiornata correttamente, si creerà più confusione che aiuto nella comprensione del codice.

Se si dispone di unit test per ciascun metodo / test di integrazione per ciascun modulo, si tratterebbe di una autocompensazione più gestibile e più facile da comprendere rispetto ai commenti sul codice.

Sì, avere una struttura di directory adeguata sicuramente aiuterà.

Personalmente sono un fan di un documento di design di alto livello - preferibilmente scritto PRIMA di qualsiasi codice - che offre una panoramica del design e un elenco di classi e risorse. Un design top-down semplifica notevolmente le cose: il tuo potrebbe essere "motore di gioco -> hardware -> controller -> joystick"; quindi, un nuovo programmatore ha detto che "aggiustare il pulsante 'a' sul 'controller xyz" avrebbe almeno saputo dove iniziare a cercare.

Troppe lingue moderne tendono a suddividere il codice in centinaia di piccoli file, quindi solo trovare il file corretto può essere una sfida anche per un progetto moderato.

Se la base di codice è grande, provo a fornire un documento di progettazione che mappi gli elementi chiave della sua progettazione e implementazione . L'intenzione qui non è quella di dettagliare nessuna delle classi utilizzate, ma fornire una chiave per codificare e il pensiero che è andato nella progettazione. Fornisce un contesto generale al sistema, ai suoi componenti e alla sua applicazione.

Le cose da includere nel documento di progettazione sono;

• Architettura dell'applicazione
• Struttura del codice logico
• Flussi di dati
• Modelli chiave utilizzati e motivazione dietro il loro utilizzo
• Struttura del codice sorgente
• Come costruirlo (questo offre informazioni sulle dipendenze implicite e sulla struttura del codice fisico)

A seguito di ciò, la documentazione per le classi e le funzioni / i metodi dovrebbero essere completate come appropriato . In particolare l'API pubblica; dovrebbe essere chiaro quali sono i seguenti in tutti i casi;

• presupposti
• effetti
• invarianti
• Condizioni di eccezione (genera)

La regola più importante che ho trovato per facilitare ai nuovi sviluppatori la comprensione di una base di codice è che l' accordo perfetto è costoso.

Se i nuovi sviluppatori devono comprendere perfettamente il sistema su cui stanno lavorando, ciò impedisce tutte le opportunità di apprendimento sul lavoro. Penso che le note del programmatore siano un ottimo inizio, ma andrei oltre. Prova a scrivere codice che, se avvicinato di nuovo, consentirebbe a uno sviluppatore di capire cosa stanno facendo al volo, piuttosto che richiedere loro di imparare prima di farlo. Piccole cose come asserzioni per casi che conosci non possono mai accadere, insieme a commenti che spiegano perché l'asserzione è valida, fanno molto. Lo stesso vale per la scrittura di codice che non riesce con garbo anziché segfault se si fa qualcosa di sbagliato.

Ho visto grandi classi con documentazione e dopo aver letto la documentazione non ho idea di cosa dovrebbe essere utile questa classe e perché qualcuno la userebbe! E allo stesso tempo, avevo bisogno di alcune funzionalità ed ero assolutamente sicuro che ci doveva essere una classe per gestirla, e non riuscivo a trovarla da nessuna parte - perché non c'era documentazione che mi guidasse da ciò di cui avevo bisogno alla classe facendolo.

Quindi la prima cosa che vorrei nella documentazione è solo qualche frase su cosa fa una classe e perché vorrei usarla. I commenti nella domanda originale stanno andando abbastanza bene al riguardo. Dopo aver letto questi commenti, se avessi un joystick che non funziona bene perché non riesco a interpretare i valori forniti, saprei quale codice controllare.

Simile a quello che ha detto @meriton, suddividere il codice in componenti separati. Ancora meglio, suddividere la base di codice in pacchetti separati (JAR, gemme, uova, qualunque cosa) per rendere ancora più chiaro il modo in cui i componenti sono separati. Se c'è un bug, uno sviluppatore deve solo trovare il pacchetto in cui si trova il bug e (si spera) risolverlo solo lì. Per non parlare del fatto che è più semplice eseguire unit test e sfruttare la gestione delle dipendenze.

Un'altra soluzione: ridurre la base di codice. Meno codice c'è, più è facile da capire. Rifattorizzare il codice inutilizzato o duplicato. Utilizzare tecniche di programmazione dichiarativa . Questo richiede sforzo, ovviamente, e spesso non è possibile o pratico. Ma è un obiettivo degno. Come ha scritto Jeff Atwood: Il miglior codice non è affatto un codice

Per sistemi complessi può valere la pena non solo documentare ogni file, ma anche le loro interazioni e gerarchia, e come le strutture del programma e perché.

Ad esempio, un motore di gioco è in genere piuttosto complesso ed è difficile decidere cosa si chiama cosa dopo centinaia di strati di astrazione. Potrebbe valere la pena creare un file come "Architecture.txt" per spiegare come e perché il codice è strutturato in questo modo e perché c'è quel livello di astrazione dall'aspetto inutile lì.

Ciò può essere in parte dovuto al fatto che è difficile per un singolo programmatore scriverlo, poiché ogni individuo comprende solo la propria parte del progetto.

A volte puoi ottenere queste informazioni dalle note del project manager, ma questo è tutto ciò che otterrai, poiché raramente riscrivono le loro note in questo formato.