Presentazione/spiegazione del codice e decisioni di progettazione ai membri del team

Question

Sto lavorando a un progetto in cui dovrò regolarmente giustificare e spiegare il mio codice e le decisioni di progettazione ai membri del team che non sono direttamente coinvolti nella stessa area del progetto sono.

Come posso spiegare al meglio le mie decisioni di progettazione tecnica ai membri del team in un altro luogo? Le procedure dettagliate del codice valgono il tempo per i membri del team non direttamente coinvolti, oppure le spiegazioni scritte e il codice annotato dovrebbero essere migliori? Se decido di commentare pesantemente il mio codice per spiegare le decisioni di progettazione, dovrei farlo in una copia separata del codice?

Answer 1

Mi piacciono gli schemi semplici disegnati a mano per le spiegazioni di progettazione. Ma devi mantenerlo molto semplice, non sovraccaricarlo con diagrammi di architettura completi e ogni piccolo dettaglio. Parlare con i colleghi del diagramma lo renderà una buona discussione e se fanno domande al riguardo il tempo vale molto più di un discorso tutto tuo.

Quando si tratta di documentare il codice, sono un grande fan di Clean Code. Se stai nominando attentamente tutto ciò dovresti lasciare una riga di commento solo se esiste una decisione progettuale dietro il codice che ti ha fatto scegliere un modo insolito. Evito generalmente molta documentazione (come javadoc) nel mio codice.

Ecco quello che faccio:

• mantenere metodi semplici
• 1 livello di dettaglio nei vostri metodi
• buoni nomi di variabili, metodi, classi

cerco anche di evitare la roba di hackery nel mio codice. Se hai bisogno di spiegare una singola riga del tuo codice, perché hai usato il modo più elegante e il più breve per fare le cose, probabilmente impazzisci The Next Developer.

E, la cosa più importante: fornire casi di test (forse unit test) per il codice, in modo che altri sviluppatori in grado di crearli, vedere cosa succede e in realtà vedere come il codice è stato destinato ad essere utilizzato. Penso che avere dei casi di test come un modo per documentare il tuo codice sia un modo davvero carino per gli altri sviluppatori di abituarsi al tuo codice. Le stesse regole si applicano ai casi di test che al codice: rendilo pulito.

Answer 2

Aggiungi buoni commenti al codice effettivo che include brevi esempi, vedere alsos ed ecc
Assicurati di includere l'aiuto HTML generato nel check-in risultati
(rende la documentazione più facile per gli altri a accesso).

Includere anche progetti/pacchetti demo nella soluzione/progetto che dimostrano i vantaggi del design e come utilizzare il codice.
Assicurati che gli esempi siano collegati agli argomenti su cui gli altri stanno lavorando, questo renderà più facile la loro connessione.

Answer 3

IMHO, commentando bene il codice è probabilmente il modo migliore per trasmettere queste informazioni. Grandi manuali o persino documenti di progettazione diventano obsoleti rapidamente con l'evolversi della base di codici. Oltre a questo, un programmatore ha meno probabilità di sedersi e sfogliare un manuale spesso che andare e cercare nel codice per capire cosa sta succedendo.

Se il codice è stato progettato abbastanza bene che la sua struttura è autodocumentante, i commenti che aggiungi per spiegare i tuoi algoritmi e tali forniranno il resto delle informazioni che altri programmatori dovranno dare un senso al tuo codice.

Come è stato menzionato, è facile estrarre i commenti per generare documenti API in molte lingue. Questa è un'altra cosa utile da fare.