Commenti
- Specifica quale lingua desideri documentare, gli standard e gli strumenti variano a seconda delle lingue .
- Inizia con questo: cosa avrebbe dovuto risolvere / fare il tuo software? Documenta i passaggi su come farlo prima di tutto.
- Trova il codice esistente nei progetti open source esistenti. Si prega di leggere il codice esistente. Quindi confrontalo con il tuo. Infine, dopo averlo fatto, fai domande specifiche in base al codice che hai trovato.
Rispondi
Dovresti documentare:
- lintento, il perché;
e
- ciò che non può essere ovvio, il come.
Perché hai ottimizzato questo bit, a cosa serve esattamente quella scorciatoia, qual è il risultato che ti aspetti, qual è il requisito, il motivo per cui è presente in primo luogo, dove vengono inviati questi dati, da dove viene linput, se è multi-thread, spiega il modello, se cè un database, spiega lo schema, i collegamenti, perché …
Non documentare lovvio. Per quanto riguarda la presentazione, ci sono molti modi per farlo. Personalmente mi piacciono i commenti in linea (sono un vecchio tipo di programmatore e non avevamo strumenti di fantasia allora – inoltre io trovalo semplice e diretto). Se vuoi qualcosa di stravagante, assicurati che non consumi troppo tempo o molto probabilmente lo abbandonerai presto.
Commenti
- Lintento è spesso la cosa più utile, posso guardare il codice e capire cosa fa, ma capire perché lo sviluppatore lo ha fatto in quel modo può essere molto utile.
Risposta
Leggi parte del tuo codice che hai scritto due o più anni fa.
Chiediti quali tipi di cose non sono chiare e lasciati a grattarti la testa durante la lettura. Quei tipi di cose (qualunque cosa siano, saranno diversi per programmatori diversi) sono ciò che vuoi iniziare a documentare per primo su ogni nuovo codice che sviluppi, o vecchio codice che riscrivi / riutilizzi. Qualsiasi formattazione che rallenti la tua comprensione , cambia.
Oppure, tra 2 anni …
Rispondi
Una cosa dovresti include sono le dipendenze. Se una funzione si basa su qualcosa di laggiù , allora doc Documenta cosè, dove si trova laggiù e perché.
Risposta
Dato che “stai utilizzando PHP, PHPDoc sarebbe un buon punto di partenza. Puoi creare la tua documentazione API in linea nel codice sorgente e quindi utilizzare lo stesso formato per scrivere tutorial e documentazione utente. Avrai anche una certa flessibilità per quanto riguarda il formato di output.
Risposta
Inizio sempre a scrivere codice scrivendo prima i miei commenti. Descrivi il flusso del programma e inizierai a capire cosa deve essere commentato e cosa no. Dopo aver iniziato a scrivere il codice, abbellisci le parti che necessitano di spiegazioni aggiuntive e perfeziona le parti che si documentano da sole.
Dopo aver completato ogni classe, funzione o metodo, torno indietro e aggiungo commenti per un generatore di documenti come doxygen o PHPDoc. Questo ti fornirà la documentazione API effettiva.
A seconda di chi utilizza il mio codice, scriverò una descrizione formale del documento operativo in LaTeX o Word.
Risposta
Doxygen copre la maggior parte delle lingue. Dovrai dedicare un po di tempo a capire la sintassi, ma il grosso problema è cosa documentare. Tratta ogni funzione come una scatola nera. Documenta cosa entra e cosa esce. Documenta quali errori intercetta, se args può essere nullo, se può restituire un valore nullo.
Ricorda, in pochi mesi non sarai in grado di capire cosa diavolo fa una funzione. Stai solo risparmiando tempo.