Come assicurarsi che il codice sorgente dell'applicazione abbia una documentazione adeguata per i nuovi programmatori? [duplicare]

Sfortunatamente, non c'è modo di "correttamente" documentare il codice sorgente. Ecco i motivi principali:

1. Che cosa sai? Se sei un apprendista, avrai bisogno di una documentazione molto più dettagliata di, ad esempio, qualcuno con 70K su stackoverflow e un gold java badge. Come puoi sapere in anticipo cosa saprà qualcuno che inizia nella tua azienda e cosa devi spiegare nella documentazione?

2. Come mantenere la documentazione e il codice sincronizzati? Il codice è verificato in molti modi: test unitari, revisioni del codice, eseguendolo in produzione. Se la documentazione è sbagliata, qualcuno deve leggerlo e notarlo. Ciò significa che i documenti invecchiano molto più velocemente del codice e la gente inizia rapidamente a non fidarsi e ignorarla, il che rende l'età ancora più veloce.

3. Quando documenti? Presto? Ciò solleva la possibilità che la documentazione risieda (si veda il punto precedente). In ritardo? Aumenta le possibilità che non sia mai stato fatto.

4. Che cosa documenti? La vista di 10.000 piedi d'uccello? Più utile e ha la più grande possibilità di rimanere utile nel tempo ma inutile il più delle volte - diciamo quando caccia un bug.

5. Perché documenti? Solo per rendere felice la gestione? Cosa sanno? O hai bisogno di documentare perché il codice è così cattivo? Che ne dici di scrivere codice leggibile invece?

Ho avuto alcune speranze con la programmazione intenzionale ma non ha funzionato ancora.

Il mio approccio attuale, basato su oltre 25 anni di esperienza, è quello di scrivere codice leggibile in primo luogo e mettere gli sforzi della documentazione nei test unitari:

• I test unitari non possono mentire
• Devono essere semplici (4-10 righe di codice)
• Spiegano ciascuna caratteristica del codice una dopo l'altra
• Sono veloci da eseguire (la regola nella nostra azienda è che tutti i test unitari devono essere eseguiti in meno di 10 secondi)

Le persone che iniziano nella nostra azienda possono eseguire il debugger con 2-3 clic del mouse e vedere come funziona il codice.

Il più grande vantaggio: devi comunque scrivere test di unità. Perché non usarli anche a scopo di documentazione?

In una parola: processo. Io lavoro nel settore aerospaziale, c'è un processo che richiede che alcuni artefatti vengano generati come parte del ciclo di sviluppo del software. Ancora un altro processo all'interno del controllo qualità assicura che questi artefatti vengano generati. Un processo di revisione garantisce che gli artefatti generati soddisfino il livello richiesto di dettaglio e accuratezza. Ancora un altro processo cancella il successo degli altri processi ecc.

È tutt'altro che perfetto, non è economico e richiede un grande sforzo per ottenere risultati. Uno sviluppatore può mantenere una base di codice di linea multi-milioni senza leggere e comprendere ogni riga di codice. Non conosco altro modo per raggiungere questo obiettivo. I codificatori del "codice è gospel" falliscono miseramente di fronte a questi sistemi complessi, complessi e in tempo reale. La documentazione non è una riflessione accurata al 100% di ciò che fa il codice, ma è una descrizione più precisa di cosa dovrebbe fare il codice rispetto al codice. Pertanto, se il codice non esegue ciò che il documento dice che dovrebbe, probabilmente il codice è sbagliato.

Non usiamo scrittori tecnologici; tuttavia, credo che dovremmo - i programmatori non sono sempre dei bravi scrittori di inglese, e l'empowerment di uno scrittore di tecnologia per trasformare il goffo technobable in inglese conciso sarebbe un piccolo investimento per grandi guadagni.

Non mi piace la documentazione. Può mentire, il codice non può. Con tutti i mezzi avete documentazione sui concetti di livello superiore dell'applicazione, ma il codice di documentazione? Questo è un grande segnale che il tuo codice non è chiaro.

Faccio comunque codice in un linguaggio di alto livello (principalmente C #) che è pseudo inglese, altri che usano un livello più basso potrebbero non essere d'accordo.

Non sono a conoscenza di nessuno che usi i redattori della tecnologia per la documentazione puramente interna, il problema, specialmente per i contenuti di livello inferiore, con la documentazione scritta è in sincronia con ciò che effettivamente fa il codice, quindi la documentazione scritta è il migliore aree che stanno per cambiare meno, vale a dire i concetti di alto livello di ciò che fa il software e perché? quali ipotesi sono state fatte e quali disegni alternativi sono stati scartati. I test possono essere utilizzati per documentare il materiale di basso livello e il loro funzionamento ti dirà se sono sincronizzati con il codice.

Per la comprensione di basso livello di come una funzione / metodo o classe è destinata a lavorare i test di unità sono la migliore forma di documentazione per il semplice motivo che eseguirli ti dice se sono sincronizzati con la base di codice corrente o meno. non qualcosa che puoi controllare con commenti o documentazione basata su testo. i test di unità automatizzati sono praticamente indispensabili per molte ragioni.

I test di integrazione e di sistema possono aiutare a documentare altre cose, come viene utilizzato il sistema? qual è il flusso di lavoro che un operatore utilizzerà? l'integrazione automatizzata e i test di sistema sono belli da avere, ma per lo meno si vogliono test manuali programmati. Potresti anche aver bisogno di qualche descrizione aggiuntiva attorno a questo livello se / quando non è possibile testare ogni caso, quindi devi catturare l'intento in un altro modo.

Ci sono cose che i test non sono così bravi a documentare, mi viene in mente l'architettura. L'architettura può essere ragionevolmente documentata con UML, anche se in un processo di basso processo a 5 minuti con una lavagna e un esperto è probabilmente abbastanza buono.

Gli sviluppatori di grandi aziende come IBM, Microsoft e Google seguono le convenzioni del codice per garantire codice ben scritto e condurre revisioni di codice per scoprire codice scritto male. Il codice scarsamente documentato si qualifica come codice scritto male.

La fonte principale di documentazione tecnica per il software è il codice sorgente, qualsiasi altra documentazione è secondaria. Gli scrittori tecnici sono generalmente impiegati per trasmettere informazioni tecniche (e possibilmente di marketing) agli utenti (opuscoli, manuali e tutorial). Gli sviluppatori dovrebbero essere soddisfatti con codice sorgente ben scritto (e documentazione API).

Un programmatore ben praticato avrebbe dovuto padroneggiare l'abitudine di documentare il proprio codice durante e non dopo la codifica (nello stesso modo in cui gli scienziati documentano i loro esperimenti durante-non-dopo). La documentazione del codice dovrebbe essere corretta, chiara e semplice. Il codice stesso dovrebbe essere auto-esplicativo per ridurre la necessità di lunghi paragrafi di spiegazione.

Esistono strumenti che è possibile utilizzare per generare documentazione API dai file di origine per linguaggi di programmazione popolari come Java (javadoc), PHP (phpdoc), Python (pydoc) e Ruby (rdoc). E anche strumenti che puoi usare per analizzare il tuo codice per errori di codifica comuni inclusa la mancanza di documentazione.