Scrivere documentazione per metodi ben compresi come uguali a Java

È una buona pratica scrivere commenti per metodi ampiamente conosciuti come uguaglianza, confronto, ecc.?

Considera il codice seguente.

 /**
 * This method compares the equality of the current object 
  with the object of same type
 */
@Override
public boolean equals(Object obj) {

               //code for equals

     }   

La mia azienda si impegna a inserire commenti come sopra. È necessario il commento Javadoc sopra? Non è ovvio e ben compreso cosa fa il metodo uguale e simili (confronta, confronta per) ecc.?

Quali sono i tuoi suggerimenti?

JavaDoc supporta già l' ereditarietà dei commenti . Secondo la documentazione, "i costruttori, i campi e le classi nidificate non ereditano i commenti doc", ma metodi come equals()will. Poiché la Objectclasse ha un equals()metodo 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 nell'IDE e nella documentazione web generata. Non è necessario riscrivere esplicitamente commenti accurati e completi che esistono in una superclasse, e direi che ingombra i file di codice.

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

Nella mia squadra di solito usiamo l' @inheritDocannotazione per equals()e, hashcode()ma vorrei non averlo fatto.

Per questi due metodi devo sempre guardare all'implementazione. Dato che stai scavalcando un metodo, ciò significa che vuoi che faccia qualcosa di diverso. Penso che questo meriti una sua documentazione.

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

Ricorda che i commenti aiutano gli sviluppatori di ogni tipo se sono corretti.

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

Ad essere onesti, confrontare 2 oggetti può essere complicato (ad esempio confrontare 2 oggetti di fattura), inoltre il tuo metodo potrebbe evolversi 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 sporcare il codice con commenti vacui come:

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

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

1. I commenti non devono mai iniziare con "Questo metodo" o "Questa classe" o "Questo" qualsiasi cosa. Il commento è associato a un metodo o a una classe dalla sua posizione nel file di origine.

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

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

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 banali metodi get / set sono i peggiori di tutti.

Il nostro standard di codifica impone che quando si esegue l'override di un metodo non è necessario documentarlo a meno che, nel sovrascriverlo, la documentazione nella classe o nell'interfaccia genitore non sia più accurata e completa per la classe secondaria o di implementazione.

Per uguali, potremmo voler notare che il confronto viene eseguito solo su una chiave primaria quando si confronta un'entità supportata dal database in quanto ciò 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 scavalcato la classe. Quindi sei mesi dopo, quando ti chiedi se è implementato o meno, sarai in grado di vedere senza aprire la classe.

Sapendo che questi metodi sono comuni e la maggior parte degli sviluppatori saprà a cosa servono, IMO, non dovrai 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 potrebbero creare 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 / modifica non è per un'API pubblica, lascia fuori i javadocs per metodi comuni in quanto questi aggiungeranno solo disordine e rumore.