Faccio molta programmazione Java al mio lavoro (sono uno stagista) e mi chiedevo se generalmente è una regola creare javadoc per accompagnare il mio codice. Di solito documento comunque ogni metodo e classe, ma trovo difficile aderire alla sintassi di Javadoc (scrivendo le variabili e l'output in modo che il parser possa generare html).
Ho esaminato molta programmazione in C e anche in C ++ e mi piace il modo in cui vengono commentati. È sbagliato non fornire javadoc con il mio codice?
In qualsiasi scrittura, scrivi per il tuo pubblico. Il tuo pubblico è lo sviluppatore della manutenzione, che potresti essere tu dopo 3 anni dopo aver dimenticato i dettagli di come tutto funziona.
Il codice throw away monouso, probabilmente può essere commentato di meno. Le API che devono essere utilizzate da altri sviluppatori devono essere documentate di più.
In nessun caso qualcuno ha bisogno di javadoc che ripete solo la firma del metodo (ad esempio "Questo è un metodo con un valore di ritorno di void e un nome di HelloWorld e viene invocato senza parametri")
Questa è generalmente una decisione di squadra / azienda; Non c'è una risposta giusta o sbagliata.
È applicabile anche al tipo di software in fase di sviluppo; esternamente esposti e consumati rispetto a quelli esposti e consumati internamente.
Con qualsiasi commento; rendili utili Non rigurgitare la firma del metodo.
Javadoc è praticamente lo standard accettato per la documentazione del codice java. Essere in grado di convertirlo in HTML è solo uno dei vantaggi; una cosa molto più importante è che tutti i principali IDE Java lo capiscono, e lo useranno per visualizzare la guida sensibile al contesto mentre si codifica. Se non si aderisce alla sintassi di javadoc, ciò non funziona e rende molto fastidioso lavorare con il proprio codice per le persone che sono abituate a questa funzione di comodità (e specialmente nel mondo Java, che codifica in un IDE piuttosto che un semplice editor di testo è la norma).
In breve, usare il tuo stile di commento è egoista, testardo e infantile. Impara javadoc. Non è così difficile, e potrebbe anche essere utile per la tua futura carriera.
Is it wrong to not supply javadoc with my code?
Sì. È sbagliato non creare significativo javadoc.
E 'sbagliato scrivere javadoc non motivato e non informativo.
Direi che è sbagliato non assicurarti che il codice che sviluppi sia chiaramente e comprensibilmente documentato per la situazione attuale. Ciò significa che è situazionale.
Come stagista, considera che tutto il codice che scrivi sarà responsabilità di qualcun altro. Ciò aumenta la posta per ciò che costituisce una documentazione comprensibile.
Per quanto riguarda javadoc in particolare, spetta a te e al tuo datore di lavoro, ma dovresti sicuramente essere sicuro che qualcosa venga lasciato dietro a un'altra persona da usare.
Se il problema è che trovi difficile aderire alla sintassi javadoc, un buon IDE ti sarà d'aiuto. Ad esempio, in Eclipse, apri un commento con / ** digita un @ e la funzionalità di completamento del codice elencherà le annotazioni disponibili.
Controllare il risultato è semplice come passare il puntatore del mouse sul nome del metodo. Ciò rende anche la ricerca della documentazione molto semplice e veloce senza passare a un browser Web per visualizzare un repository di documentazione.
JavaDoc semplifica l'utilizzo del codice. Dubito che sia di aiuto migliore dei normali commenti quando si parla di bugfixing o di modifica del codice, ma l'utilizzo delle classi in altri progetti è di gran lunga più semplice e quindi più probabile quando i commenti di JavaDoc consentono ad altri programmatori di trovare e utilizzare classi e metodi. Dato che il riutilizzo del codice è generalmente meglio che reinventare la ruota, l'omissione di JavaDoc è difficilmente accettabile a meno che il tuo codice sia così cattivo che il riutilizzo non è comunque un'opzione.
Leggi altre domande sui tag java comments documentation