Come posso documentare il mio codice? [duplicare]

Devi documentare:

• l'intento, il perché;

e

• quello che potrebbe non essere ovvio, il come.

Perché hai ottimizzato questo bit, a cosa serve esattamente questa scorciatoia, qual è il risultato che ti aspetti, qual è il requisito, il motivo per cui è lì, in primo luogo, dove vengono inviati questi dati, dove ti trovi? ottenere l'input da, se questo è multi-thread, spiegare il modello, se c'è un database, spiegare lo schema, i collegamenti, perché ...

Non documentare l'ovvio. Per quanto riguarda la presentazione ci sono molti modi per farlo. Personalmente mi piacciono i commenti in linea (io sono un vecchio tipo di programmatore e all'epoca non avevamo strumenti fantastici - in più lo trovo semplice e diretto). Se vuoi qualcosa di particolare, assicurati che non consumi troppo tempo o molto probabilmente lo abbandonerai presto.

Leggi un po 'del tuo codice che hai scritto 2 o più anni fa.

Chiediti quali tipi di cose non sono chiari e lasciati graffiare la testa mentre leggi. Questi tipi di cose (qualunque esse siano, saranno differenti per i diversi programmatori) sono ciò che vuoi iniziare a documentare prima su qualsiasi nuovo codice che sviluppi, o vecchio codice che riscrivi / riutilizzi. Qualsiasi formattazione che rallenti la tua comprensione, cambia.

Oppure, in 2 anni ...

Una cosa che dovresti includere sono le dipendenze. Se una funzione si basa su qualcosa di laggiù quindi documenta cosa è, dove là è, e perché.

Dato che stai usando PHP, PHPDoc sarebbe un buon punto di partenza. È possibile creare la documentazione dell'API in linea nell'origine e quindi utilizzare lo stesso formato per scrivere esercitazioni e documentazione utente. Avrai anche una certa flessibilità per quanto riguarda il formato di output.

Comincio sempre a scrivere il codice scrivendo prima i miei commenti. Descrivi il flusso del programma e inizierai a realizzare ciò che deve essere commentato, e cosa no. Dopo aver iniziato a scrivere il codice, abbellisci le parti che necessitano di ulteriori spiegazioni e perfeziona le parti che si documentano da sole.

Dopo che ogni classe, funzione o metodo è completo, torno indietro e aggiungo commenti per un generatore di documenti come doxygen o PHPDoc. Questo ti fornirà la vera documentazione dell'API.

A seconda di chi consuma il mio codice, scriverò una descrizione formale del documento operativo in LaTeX o Word.

Doxygen copre la maggior parte delle lingue. Dovrai dedicare un po 'di tempo a capire la sintassi, ma il grosso problema è cosa documentare. Tratta ciascuna funzione come una scatola nera. Documenta cosa va e cosa esce. Documenta quali errori intercetta, se gli argomenti possono essere nulli, se può restituire un valore null.

Ricorda, in pochi mesi non sarai in grado di capire cosa diavolo fa una funzione. Stai solo risparmiando tempo.