Pisanie dokumentacji dla dobrze zrozumiałych metod takich jak równa się w Javie

Czy dobrą praktyką jest pisanie komentarzy do powszechnie znanych metod, takich jak równość, porównywanie itp.?

Rozważ poniższy kod.

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

               //code for equals

     }   

Moja firma nie chce dodawać komentarzy jak wyżej. Czy powyższy komentarz Javadoc jest wymagany? Czy nie jest oczywiste i dobrze zrozumiane, co robi metoda równości i polubień (porównaj, porównaj) itp.?

Jakie są twoje sugestie?

JavaDoc już obsługuje dziedziczenie komentarzy . Zgodnie z dokumentacją „konstruktory, pola i klasy zagnieżdżone nie dziedziczą komentarzy do dokumentu”, ale metody takie jak equals()will. Ponieważ Objectklasa ma dobrze udokumentowaną equals()metodę, powinieneś być w stanie odziedziczyć tę dokumentację bez problemu.

Dokumentacja metody musi skądś pochodzić, aby była dostępna w twoim IDE i wygenerowanej dokumentacji internetowej. Jawne przepisywanie dokładnych i wyczerpujących komentarzy, które istnieją w nadklasie, nie jest konieczne, i argumentowałbym, że pliki kodu są zaśmiecone.

Jeśli jest to polityka korporacyjna, masz dwie opcje. Możesz z nim postępować elegancko i poradzić sobie z dodatkowym wysiłkiem związanym z pisaniem i utrzymywaniem dokumentacji (często z naruszeniem zasady DRY, która może być również stosowana do dokumentów, a także kodu). Inną opcją byłoby poszukiwanie polityki firmy - wyjaśnienie, dlaczego ta polityka nie jest dobrym pomysłem i korzyści z jej zmiany (pod względem czasu, pieniędzy, wysiłku, jakości - rzeczy, które kierownictwo rozumie).

W moim zespole zazwyczaj używamy @inheritDocadnotacji dla equals()a hashcode(), ale żałuję, że nie.

Dla tych dwóch metod zawsze muszę spojrzeć na implementację. Ponieważ zastępujesz metodę, oznacza to, że chcesz, aby zrobiła coś innego. Myślę, że to zasługuje na własną dokumentację.

Dobrze jest przynajmniej udokumentować, jakie atrybuty biorą udział w metodzie, a może nawet dlaczego.

Pamiętaj, że komentarze pomagają programistom wszelkiego rodzaju, jeśli są poprawne.

Problem polega na tym, że czasami są one niekompletne i niedokładne.

Szczerze mówiąc, porównywanie 2 obiektów może być trudne (np. Porównywanie 2 obiektów faktury), również twoja metoda może ewoluować z czasem i wtedy trzeba będzie ją skomentować.

Dobrze jest pokazać cel metody, reguły itp. W komentarzu „przydatnym i znaczącym”.

Niezwykle słabą praktyką jest zaśmiecanie kodu pustymi komentarzami, takimi jak:

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

To nie mówi nic przydatnego. Gorzej, jest kiepski zarówno pod względem stylu, jak i gramatyki:

1. Komentarze nigdy nie powinny zaczynać się od „This method”, „This class” lub „This”. Komentarz jest powiązany z metodą lub klasą przez jej położenie w pliku źródłowym.

2. „obiekt” powinien brzmieć „obiekt”

3. „Porównuje równość” ma sens tylko wtedy, gdy jeden obiekt może mieć więcej „równości” niż inny. Ta funkcja nie porównuje „równości”; porównuje obiekty w celu ustalenia ich równości między sobą.

Zamiast tego komentarz powinien wskazywać, kiedy dwa obiekty są uważane za równe. Tutaj całkowicie pominąłbym opis metody i dokumentuję tylko wartość zwracaną, na przykład:

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;
  }
...
}

Najgorsze są wygenerowane komentarze do trywialnych metod get / set.

Nasz standard kodowania nakazuje, że podczas nadpisywania metody nie jest konieczne jej udokumentowanie, chyba że podczas nadpisywania dokumentacja w klasie nadrzędnej lub interfejsie nie jest już dokładna i wyczerpująca dla klasy podrzędnej lub implementacyjnej.

W przypadku równości możemy chcieć zauważyć, że porównanie jest wykonywane tylko na kluczu podstawowym podczas porównywania jednostki opartej na bazie danych, ponieważ nie jest to całkowicie spójne z dokumentacją Object.equals().

Moim zdaniem i myślę, że może to być kontrowersyjne, powinieneś wskazać w komentarzu, w której klasie przesłoniłeś klasę. Potem, sześć miesięcy później, kiedy zastanawiasz się, czy to jest zaimplementowane, czy nie, będziesz mógł zobaczyć bez otwierania klasy.

Wiedząc, że te metody są powszechne i większość programistów będzie wiedzieć, do czego służą, IMO, nie będziesz musiał umieszczać tam żadnych komentarzy. Komentarze nie są tak wiarygodne na dłuższą metę, ponieważ są szanse, że nie zostaną one zaktualizowane po zaktualizowaniu implementacji i mogą spowodować zamieszanie. Dlatego zawsze lepiej jest uczynić kod czytelnym, ponieważ jest to coś, co można w większości zaufać.

Ponadto powiedziałbym, że jeśli kod, który tworzysz / edytujesz, nie jest przeznaczony dla publicznego interfejsu API, po prostu pomiń javadocs dla typowych metod, ponieważ dodadzą one bałaganu i hałasu.