Come creare documentazione di Doxygen che aiuti a comprendere il codice?

Question

Come creare documentazione di Doxygen che aiuti a comprendere il codice?

#1 da (2 voti)

3

Quindi alcuni anni fa mi sono imbattuto in una dichiarazione secondo cui la maggior parte della documentazione generata da Doxygen è piuttosto brutta. "Cattivo" nel senso che sfida lo scopo della documentazione e non aiuta a comprendere il codice. In una certa misura, penso che questo si applichi anche ad altri generatori di documentazione automatica.

La maggior parte delle cose Doxygen-ated che ho visto andava bene; potresti lavorarci. Ovviamente c'è sempre la mela davvero pessima che lascia cicatrici nella tua memoria.

Finora, non ho trovato documentazione che mi abbia fatto andare: "Oh, wow, questo è scritto davvero bene, lo adoro."

Le mie domande:

Cosa dovrebbe fare uno sviluppatore per evitare di generare automaticamente una cattiva documentazione che non aiuti gli sviluppatori futuri?
E ci sono altre cose che potrebbero essere fatte per rendere la documentazione generata automaticamente buona in modo che aiuti gli sviluppatori futuri?

quality documentation

posta datenwolf 16.10.2014 - 10:52

fonte

1 risposta

Leggi altre domande sui tag quality documentation

test dell'unità su ARM Come dire che un codice Javascript ha già bisogno di AMD (RequireJS, ...)?

score 2 · Answer 1

Il pubblico della documentazione generata sono sviluppatori che stanno cercando di utilizzare il codice. Significa che il codice è una libreria o un framework riutilizzabile.

Se il codice è denominato e strutturato correttamente, la documentazione non è così importante. Ho trovato che la documentazione più importante è a livello di classe o modulo (spazio dei nomi, pacchetto, ecc.). La documentazione meno importante è a livello di funzione o metodo.

Per rendere la documentazione significativa e utile per gli sviluppatori, assicurati di descrivere lo scopo delle classi e il modo in cui sono utilizzate insieme . Se ho un es. PrintJob class, so di cosa si tratta. Ma come interagisce con PrintManager o PrinterProperties ? Qual è il processo di prendere un oggetto e stamparlo? Come funzionano questi oggetti insieme? Mi aspetto di vedere un esempio di codice breve che mostra le interazioni di classe.

La documentazione generata deve includere anche pre e post-condizioni in inglese semplice a livello di funzione, ove appropriato. Se la tua funzione print() si aspetta che un lavoro sia in un certo stato, dimmelo. Non voglio scavare nel codice per decifrare ciò di cui ha bisogno. Una volta terminata la stampa, posso riutilizzare il lavoro per stampare una seconda copia o non è più valido?

Infine, ometti la documentazione per le entità che sono veramente semplici e non ne hanno bisogno. Se hai un List , non è necessario documentare la funzione size() . Capisco che sarà un numero intero non negativo e, in base al tipo di dati, so quanto può essere grande. Questo riduce la peluria. Quando scrivo la documentazione, so che se vedo del testo, è importante. Non sta documentando qualcosa che è di buon senso per uno sviluppatore.