Quando scrivere la documentazione del progetto software sul codice [duplicato]

Question

Quando scrivere la documentazione del progetto software sul codice [duplicato]

#1 da (2 voti)
#2 da (0 voti)

1

Di solito scrivo i miei progetti software in java, e sono ancora un po 'confuso su quando documentare le mie classi, interfacce e metodi.

Ci sono due modi:

1) Scrivi la documentazione dopo aver dichiarato o codificato una classe / interfaccia / metodo / costruttore. In questo modo sono sicuro che la documentazione viene gestita immediatamente.

Svantaggio: potrei modificare gli argomenti di un metodo / costruttore o potrei modificare la funzionalità della classe o dell'interfaccia e dimenticare di modificare la documentazione.

2) Scrivi la documentazione dopo aver terminato il progetto (o una finitura / versione principale del progetto), in questo modo sono sicuro di documentare tutte le funzionalità / argomenti di metodi / costruttori e di documentare tutte le eccezioni generate.

Svantaggio: di solito diventa un altro grande compito travolgente per passare attraverso centinaia di classi e metodi alla fine del progetto, cercando di scrivere il codice della documentazione.

Come puoi vedere entrambi gli scenari hanno i loro svantaggi, ma penso che uno sia più vantaggioso dell'altro. Sono perplesso su cosa. Inoltre non sto implicando questo solo in Java, può essere applicato a qualsiasi linguaggio di programmazione che richiede documentazione.

java documentation project

posta Jevison7x 20.11.2013 - 11:53

fonte

2 risposte

Leggi altre domande sui tag java documentation project

Algoritmo del percorso di massimizzazione del peso (vertici pesati) API per la spiegazione di complicati calcoli o regole aziendali?

score 2 · Answer 1

In realtà suggerisco di scrivere una documentazione di una classe o di una funzione immediatamente prima iniziando a implementarla per ottenere una visione chiara di quali siano i requisiti e le responsabilità di quella funzione o classe. Leggere la documentazione dopo aver ottenuto una versione della funzione o della classe pronta, e rileggerla di nuovo quando si modifica qualcosa. Rendi i documenti completi ad ogni revisione del codice (fai le revisioni del codice, vero?).

E pensa anche a "ho davvero bisogno di quel commento, o posso rendere i nomi di funzioni o classi, nomi di parametri ecc. più auto-descrittivi?" Eliminare i documenti non necessari è IMHO la chiave più importante per mantenere i documenti e il codice sincronizzati.

score 0 · Answer 2

"In questo modo sono sicuro di documentare la piena funzionalità"

Non dovresti documentare la funzionalità ma il contratto l'API che il tuo metodo forma. vale a dire quali parametri si aspetta e cosa ritorna al chiamante (+ Eccezioni che può generare). La funzionalità (dettagli interni) non dovrebbe essere l'attività del contesto del chiamante. Ma se questo è il caso, il tuo metodo fa uso di effetti collaterali e questo è un mortale antipattern.

Comunque, suggerirei di immidiare la documentazione: parametri, materiale restituito, eccezioni, nient'altro.