Abbiamo bisogno di informazioni "evidenti" sulla documentazione?

Il punto di javadocs è quello di fornire informazioni che non sono immediatamente evidenti dalla semplice lettura della firma del metodo. Altrimenti, è solo uno spreco di spazio. Non sono d'accordo con le persone che dicono che non dovresti rimuovere i commenti inutili solo per rimuovere: quei commenti sprecano tempo per gli sviluppatori, dal momento che gli sviluppatori non sapranno che sono inutili fino a quando non li leggeranno. Vai avanti ed elimina.

Ma un'idea ancora migliore è di modificarla in modo che fornisca informazioni utili.

Prima:

/** Sets the monkeyName field.
 * @param name - the monkey's name.
 */
public void setMonkeyName(String name) {

Dopo:

/** Validates and stores the monkey's name per RFC 420, Monkey Enterprise Data Protocol.
 * 
 * @throws IllegalArgumentException if the name fails validation
 */

"Ovvio" è "ovviamente" soggettivo.

Di certo non andrei a rimuovere i commenti "ovvii" del codice solo per il gusto di farlo, o per riordinare le cose (secondo la tua opinione).

Potrebbe valere la pena una riunione del team di sviluppo per discutere i commenti di livello che devono essere presenti da ora in poi.

Partecipare a una missione di cancellazione per il solo scopo è di infastidire le persone.

Questa è una domanda molto attuale per me, come nel codice legacy con cui lavoro, la maggior parte dei Javadoc rientra in questa categoria. Generalmente è autogenerato, con nessuna informazione utile aggiunta a mano, o informazioni non aggiornate (o copiate non modificate da Javadoc di un altro metodo).

Il più fastidioso è il Javadoc autogenerato per getter e setter banali su classi POD (ne abbiamo molti). Quando vedo una classe con 50 o più campi, che contiene non molto più di getter e setter per questi campi, e l'inutile Javadoc che occupa più della metà dello schermo, spesso lo rimuovo completamente.

Javadoc per metodi non banali è un caso diverso. Se contiene informazioni utili e / o è per un metodo pubblico, preferisco tenerlo (e migliorarlo se possibile).

La tua domanda è dovrei eliminarle a favore di "codice di autocertificazione"

Ignorando l'inevitabile argomento del loro valore, non dovresti rimuoverli se sono già presenti. Se ti infastidiscono, modifica le impostazioni di piegatura del codice nel tuo IDE.

Non è necessario preoccuparsi di dover modificare in due punti su una modifica (codice / commenti) in quanto sarebbe necessario aggiungere Javadoc in ogni caso se metodi come "save" hanno fatto qualcosa che non è ovvio nella firma del metodo .

Io uso questa regola.

Se il codice stesso è auto-documentante, non c'è bisogno di questi commenti ovvi. Ma durante la revisione del codice se il revisore del codice ritiene che sia difficile capire il codice nella prima revisione, ciò significa che il codice necessita di alcuni commenti. Vorrei andare e aggiungere questi commenti.

Anche se il codice è influenzato da funzionalità interne come la sicurezza / cache dei thread, è meglio aggiungere commenti al codice che indica che

/* This code is not thread safe */ etc

Someone's obvious can turn out to be other person's mystery.

Dipende dal contesto per sapere cosa è prezioso o meno:

In alcuni casi, una cosa ovvia potrebbe non essere una buona cosa: ad esempio, * Se il commento è corretto, la traduzione di una narrazione è codificata così com'è che non c'è davvero alcun valore nel leggerla.

Tuttavia, a volte puoi rispondere

why is this method useful?

o anche meglio -

"Don't supply NULL value - there is No ASSERT here" -

questo sarebbe ovvio per qualcuno che ha scritto un codice, ma evita grandi fessure a qualcuno che legge per la prima volta.

Le cose più comuni che non vengono commentate perché le cose dello sviluppatore è ovvio - sono il nome e il significato delle variabili (o anche dei metodi a volte) e quasi sempre troviamo lo peer developer che si sta strappando capelli troppo spesso.

Si potrebbe rispondere meglio in due parti:

Caso generale - Se il progetto verrà elaborato da più di una persona e la documentazione del metodo verrà pubblicata in modo tale da poter essere letta separatamente dal codice stesso (es. un sito web con Javadoc pubblicato), la documentazione del metodo dovrebbe essere presente e accurata poiché prima qualcuno potrebbe andare al Javadoc. Quando lavori su un progetto in cui è coinvolta un'API, questo diventa ancora più importante in quanto non dovresti leggere il codice sorgente dell'API per determinare se puoi o non puoi fare qualcosa.

Caso specifico - Per il caso specifico che ti viene fornito, probabilmente li pulirò e li lascerò sul posto se solo così puoi utilizzare la capacità di ricerca del tuo IDE per trovare un metodo. Nell'esempio che fornisci sopra, a meno che tutti i metodi save nel programma inizino con la convalida, dovrebbe essere menzionato nel commento. Se la convalida si trova in un'altra funzione chiamata dal metodo save , è probabile che venga rimossa dal commento.

Se questo progetto ha una longevità, dovresti conservare la documentazione ovvia. È ovvio che una funzione chiamata save "convalida e salva", ma non avrei mai immaginato che save convalidi, poiché non è chiamato validateAndSave . Come altri hanno già detto, è difficile definire ciò che è ovvio; forse l'ovvietà deriva dalle convenzioni, come "ogni funzione di salvataggio è valida". Se qualcuno proviene da un progetto diverso con diverse convenzioni, potresti finire con molti metodi con nomi simili che rientrano in due categorie. Poi abbiamo "metodi di Ben save convalidare e salvare, e i metodi di Don save registrano un meccanismo di controllo e salvano".

A meno che il metodo faccia esattamente quello che ha detto e assolutamente nient'altro (a parte setter e getter, penso che sia relativamente raro), hai bisogno della documentazione.

I commenti ridondanti infastidiscono anche me.

Il mio consiglio sarebbe di sostituirli con qualcosa di meglio. L'eliminazione ti apre per mancare qualcosa e per eliminare commenti utili. Se sei abbastanza fiducioso da ricomporre il metodo, dovresti comprenderlo abbastanza da prevenire eventuali insidie.

Is there any reason to keep these obvious "Java Doc" comments or should I prune them in favor of "self documenting code" and only make Java Doc comments for less obvious methods?

Il tuo codice dovrebbe essere auto-documentato e avere commenti. Poiché metà dei tuoi commenti non sono in stile Java Doc, ti suggerisco di eliminare gradualmente i commenti in stile Java Doc. La coerenza può essere molto utile con i commenti, non ha senso implementare uno stile per metà del tempo.