Java Doc - Anche i campi vengono documentati?

Question

Java Doc - Anche i campi vengono documentati?

#1 da (3 voti)

4

Questa è una domanda molto semplice, ma stranamente, trovo difficile ottenere una risposta definitiva ....

Che cosa fai con i campi? È valido?

/** 
 * Keeps track of all usernames in the system.
 */   
private List<String> usernames = new ArrayList<>();

O è sopra ingannato dagli strumenti di documentazione, quindi sarebbe meglio fare qualcosa del tipo:

 //Keeps track of all usernames in the system.   
private List<String> usernames = new ArrayList<>();

Poiché (da quello che vedo), la documentazione mostra solo metodi, costruttori e classi, cosa fanno di solito i programmatori con i campi?

java javadocs

posta benscabbia 24.12.2014 - 16:26

fonte

1 risposta

Leggi altre domande sui tag java javadocs

Come lavori con le funzioni asincrone, in modo ricorsivo? incapsulamento: tutte le proprietà dovrebbero essere private e protette?

score 3 · Accepted Answer

I campi privati di solito ignorati dagli strumenti di documentazione, quindi quando spedisci la tua API a una terza parte, lui / lei non sarà in grado di vedere alcuna documentazione riguardante i campi privati (a meno che tu non specifichi che Voglio anche includere campi privati nella documentazione durante la fase di generazione della documentazione del tuo progetto).

Detto questo, penso che sia una buona idea usare JavaDoc anche per documentare i campi privati perché:

Sarà conforme al resto dell'altra documentazione.
La maggior parte degli IDE estrae JavaDoc e te lo mostra quando provi ad accedere a diverse proprietà dell'oggetto. Questo può far risparmiare tempo attorno al codice per vedere qual è lo scopo di una particolare variabile.
Nel caso in cui tu voglia includere la documentazione del campo privato nella tua documentazione, tutto il lavoro sarà già stato fatto.