Documentazione di scrittura per metodi ben compresi come gli uguali in Java

JavaDoc supporta già ereditando commenti . Secondo la documentazione, "costruttori, campi e classi annidate non ereditano i commenti del doc", ma metodi come equals() lo faranno. Poiché la classe Object ha un metodo equals() ben documentato, dovresti essere in grado di ereditare quella documentazione senza problemi.

La documentazione per il metodo deve provenire da qualche parte in modo che sia accessibile nel tuo IDE e nella documentazione web generata. La riscrittura esplicita di commenti accurati e completi che esistono in una superclasse non è necessaria, e vorrei discutere di clutter sui file di codice.

Se questa è una politica aziendale, allora hai due opzioni. Potete seguirlo con cura e occuparvi dello sforzo extra di scrivere e conservare la documentazione (spesso in violazione del principio DRY, che può essere applicato anche a documenti e codice). L'altra opzione sarebbe quella di cercare una politica aziendale - spiegare perché questa politica non è una buona idea e i benefici di cambiarla (in termini di tempo, denaro, impegno, qualità - cose che la direzione comprende)

Nel mio team usiamo solitamente l'annotazione @inheritDoc per equals() e hashcode() ma vorrei che non lo facessimo.

Per questi due metodi devo sempre considerare l'implementazione. Poiché stai sovrascrivendo un metodo, significa che vuoi che faccia qualcosa di diverso. Penso che questo meriti la sua documentazione.

È bene documentare almeno quali attributi partecipano al metodo e forse anche perché è così.

Ricorda che i commenti aiutano gli sviluppatori di tutti i tipi se sono corretti.

Il problema è che a volte sono incompleti e non accurati.

Per essere onesti, confrontare 2 oggetti può essere complicato (ad esempio confrontare 2 oggetti di fattura), anche il tuo metodo potrebbe evolvere nel tempo e quindi dovrebbe essere commentato.

Mostrare l'obiettivo del metodo, le regole, ecc. in un commento "utile e significativo" è una buona cosa.

È estremamente povera pratica sparpagliare il codice con commenti vuoti come:

/**
 * This method compares the equality of the current object with the object of same type...
 */

Questo non dice nulla di utile. Peggio ancora, è povero sia nello stile che nella grammatica:

1. I commenti non dovrebbero mai iniziare con "Questo metodo" o "Questa classe" o "Questo" nulla. Il commento è associato a un metodo o una classe in base alla sua posizione nel file di origine.

2. "l'oggetto" dovrebbe leggere "un oggetto"

3. "Confronta l'uguaglianza" ha senso solo se l'unico oggetto può avere più "uguaglianza" di un altro. Questa funzione non confronta "l'uguaglianza"; confronta gli oggetti per determinare la loro uguaglianza l'uno con l'altro.

Invece, il commento dovrebbe indicare quando i due oggetti sono considerati uguali. Qui, ometterei completamente la descrizione del metodo e documenterei solo il valore restituito, ad esempio:

public class Fraction {
  private int numerator, denominator;
  /**
   * @return true if <i>this</i> is numerically equal to <i>other</i>
   */
  public boolean equals(Fraction other) {
    return numerator * other.denominator == other.numerator * denominator;
  }
...
}

I commenti generati per i banali metodi get / set sono i peggiori di tutti.

Il nostro standard di codifica impone che quando si sovrascrive un metodo non è necessario documentarlo a meno che, in sovrascrittura, la documentazione nella classe genitore o nell'interfaccia non sia più accurata e completa per la classe sub o di implementazione.

Per gli uguali, potremmo voler notare che il confronto viene eseguito solo su una chiave primaria quando si confronta un'entità basata sul database in quanto non è del tutto coerente con la documentazione per Object.equals() .

Secondo me, e penso che questo possa essere controverso, dovresti indicare nel commento in quale classe hai sovrascritto la classe. Poi sei mesi su tutta la linea quando ti chiedi se è implementato o no, sarai in grado di vedere senza aprire la lezione.

Sapendo che questi metodi sono comuni e la maggior parte degli sviluppatori saprà a cosa servono allora, IMO, non sarà necessario inserire alcun commento. I commenti non sono così affidabili a lungo termine poiché ci sono possibilità che questi non vengano aggiornati quando l'implementazione viene aggiornata e potrebbe causare confusione. Quindi è sempre meglio rendere leggibile il tuo codice, poiché questo è ciò di cui ti puoi fidare maggiormente.

Inoltre, direi che se il codice che stai creando / modificando non è per un'API pubblica, lascia fuori i javadoc per i metodi più comuni, in quanto questi aggiungono solo ingombro e rumore.