Przebudowałem klasę i przeniosłem kod z konstruktora do statycznego inicjalizatora. Co powinienem zrobić z javadoc, który był na konstruktorze? Czy jest możliwe dodanie javadoc do statycznego inicjalizatora?Jak mogę dodać javadoc do inicjalizatora statycznego w Javie?
Przede wszystkim, to jest dyskusyjne czy inicjalizatory statyczne są dobre praktyki na początek.
Jeśli jednak zdecydujesz się na ich użycie, dodam dokumentację do JavaDoc na poziomie klasy. Inicjatory statyczne mogą, w zależności od sposobu ich wdrożenia, powodować działania niepożądane. Jeśli używasz statycznych inicjalizatorów z efektami ubocznymi, zachowanie powinno być udokumentowane dla konsumenta wspomnianej klasy.
JavaDoc jest przeznaczony przede wszystkim do dokumentowania interfejsu klasy. Komentarze JavaDoc muszą poprzedzać deklarację klasy, pola, konstruktora lub metody.
Statyczny inicjator nie jest częścią interfejsu. Jest to część implementacji klasy.
Możesz udokumentować swoje zachowanie w dokumentacji klas, jeśli chcesz.
Statyczny inicjator klasy może mieć efekty uboczne, które warto udokumentować. Chociaż można się spierać, czy inicjatory statyczne są dobrą praktyką na początek. – Waldheinz
Czy prywatne metody i pola są częścią interfejsu? – tttppp
@tttppp Są one "prywatne", a zatem nie są częścią interfejsu. – Waldheinz
Powiedziałbym ważne części tej dokumentacji powinny zostać przeniesione do dokumentacji klasy:
/**
* Your text here.
*/
public class SomeClass {
static {
/* your static initalizer */
}
}
Nie ma czegoś takiego jak konstruktor statyczny w Javie (as oposed to C#), dlatego należy udokumentować to zachowanie na poziomie klasy.
Ponadto, ponieważ inicjalizator statyczny najprawdopodobniej zainicjalizuje niektóre pola statyczne, jeśli te pola są publiczne, chronione (lub pakietowo prywatne, w zależności od konwencji widoczności JavaDoc), należy podać szczegóły dotyczące sposobu, w jaki te pola są zainicjalizowane w oparciu o zachowanie statycznego inicjalizatora.
+1 za "nieprzyjemne efekty uboczne" – Waldheinz