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

10

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?

Vinoth Kumar CM
źródło
3
Twój obecny komentarz jest niepoprawny. Podpis metody jest poprawny przy pobieraniu ogólnego obiektu, ale w komentarzu jest napisane „obiekt tego samego typu”.
c_maker
4
Wolę zobaczyć komentarz wyjaśniający, co równość oznacza dla tego obiektu. „Równość” jest śliskim terminem. W Common Lisp istnieje wiele funkcji równości, a ty wybierasz odpowiednią przy użyciu.
David Thornley,
W tym przypadku odnoszę się do dwóch obiektów, które są „równe” w „znaczący sposób”. Na przykład dwa obiekty pracownika są równe, jeśli mają ten sam identyfikator pracownika, zamiast twierdzić, że noszą koszulę tego samego koloru.
Vinoth Kumar CM
6
@Vinoth: „znaczący sposób” jest dokładnie tym, co musisz udokumentować :)
c_maker

Odpowiedzi:

6

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).

Thomas Owens
źródło
Mam świadomość dziedziczenia. Ale firma „upoważnia” nas do pisania wyraźnych dokumentów Java.
Vinoth Kumar CM
3
@Vinoth Jeśli taka jest polityka firmy, nic nie możesz zrobić poza napisaniem jej lub próbą zmiany polityki. Jeśli korzystasz z nowoczesnych narzędzi programistycznych, ta zasada jest nieaktualna. Co napędza tę politykę? Komentarze JavaDoc są przekształcane w strony internetowe, a nowoczesne środowiska IDE umożliwiają przeglądanie komentarzy JavaDoc podczas pisania oprogramowania, niezależnie od tego, skąd pochodzi komentarz (jawny lub odziedziczony).
Thomas Owens
@ Thomas: Istnieje prośba o wybaczenie niż prośba o pozwolenie: po prostu cicho nagnij reguły i sprawdź, czy ktoś narzeka.
dsimcha
@dsimcha Być może, ale jeśli się powtórzy, może to źle wpłynąć na pracę. To nie jest jednorazowa sprawa.
Thomas Owens
9

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.

c_maker
źródło
1
Twoje ostatnie oświadczenie jest najlepszym powodem do samodzielnego udokumentowania. Wyjaśnij, co robi. Na pewno equale () może porównać każdy element w klasie, możesz też po prostu porównać wszystkie pola łańcuchowe lub coś innego.
Nicholas
2

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”.

Bez szans
źródło
2

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.

Kevin Cline
źródło
1

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().

Kris
źródło
0

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.

Peter Taylor
źródło
0

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.

Bob Santos
źródło