Przestarzałe vs. zmigrowane w JavaDoc?

11

W JavaDoc dla X509Certificate getSubjectDN()tego stwierdza:

Przeniesiony , zastąpiony przez getSubjectX500Principal ().

Przyzwyczaiłem się do wycofywania metod for, które nie powinny być już używane, ale nie poddane migracji. Znalazłem raport o błędzie dotyczący tego konkretnego przypadku, w którym został zamknięty z komentarzem:

To nie jest błąd. „Przestarzałe” należy stosować tylko w poważnych przypadkach.

Gdy używamy metody przestarzałej , ogólnie sugerowanym działaniem jest zaprzestanie jej używania.

Jakie jest sugerowane działanie, gdy metoda jest oznaczona jako Denigrated ?

java terminology javadocs

— Jacob Schoen
źródło

2

Łał. Przeczytałem odpowiedzi i chociaż jestem pewien, że są one technicznie poprawne, „Denigrated” to okropne słowo, którego można użyć. Powinni po prostu użyć słowa „Zniechęcony”. Nie trzeba pluć na kod; wystarczyłoby ostrzeżenie.

— Eric King,

@Eric King I trochę tak czułem. Zastanawiałem się bardziej nad tym, że jeśli jest to zniechęcone, po prostu je zaniedbuj.

— Jacob Schoen,

9

Definicja denigrate Merriam-Webster sugeruje:

1: zaatakować reputację: zniesławić <oczernić przeciwników>
2: zaprzeczyć ważności lub ważności: belittle <oczernić ich osiągnięcia>

Na podstawie tego, co napisano w innym pokrewnym błędzie, zniesławienie / belittle wydaje się pasować do zamiaru sformułowania używanego w javadocs - Bug ID: 4959744 Denigrate X509Certificate.getSubjectDN () & co :

Metody getSubjectDN () i getIssuerDN () w X509Certificate i getIssuerDN () w X509CRL są problematyczne . Zwracają nieokreśloną klasę implementującą interfejs java.security.Principal, który ma bardzo luźną specyfikację.

Ponieważ żadna dodatkowa specyfikacja nie występuje w metodach getSubjectDN () i getIssuerDN (), implementacje mogą zwrócić dowolną klasę specyficzną dla implementacji. Doświadczenie ze świata rzeczywistego pokazało, że dzieje się tak w przypadku braku możliwości przenoszenia lub zawodności kodu. Ze względu na zgodność specyfikacji tych metod nie można zmienić i należy je uznać za niemożliwe do odzyskania.

Metody zastępcze getSubjectX500Principal () i ko, które zwracają instancję dobrze zdefiniowanej klasy X500Principal zostały dodane w JDK 1.4. Implementacje tych metod zostały zaprojektowane w celu uniknięcia wszystkich tego rodzaju problemów. Jednak nowe metody cierpią z powodu niedoświetlenia, a programiści nadal używają znanych i bardziej intuicyjnie nazwanych metod getSubjectDN () i co.

Aby to zmienić, stare metody getSubjectDN () i getIssuerDN () powinny być przestarzałe. Dzięki temu programiści korzystający z tych metod otrzymają ostrzeżenie o czasie kompilacji ....

OCENA

... W tym przypadku wycofanie uznano za nieodpowiednie. Zamiast tego do JavaDoc dodano ostrzeżenia .

Fakt, że odczytanie błędu ID 5008142 sprawiło, że jesteś zdezorientowany co do tych „oczernianych” rzeczy, wygląda bardziej jak wina programisty, który sobie z tym poradził.

Powinni byli znaleźć błąd 4959744 i odnieść go do swojej oceny, zamiast niejasnego stwierdzenia „przeznaczony do użycia tylko w poważnych przypadkach”. Prawdopodobnie mogą się nawet zamknąć jako duplikat, z uzasadnieniem takim jak „Zastrzeżenie zostało rozważone, ocenione i odrzucone na korzyść oczernienia na podstawie błędu ID 4959744” .

Przynajmniej mogliby odwołać się do identyfikatora błędu 4959744 (być może wraz z 4638294 ) w polu Powiązane raporty (o nazwie Zobacz także w starym bugs.sun.com iirc) swojego narzędzia do śledzenia błędów. To, że tego nie zrobiono, sprawia, że podejrzewa się, że wcale nie szukali powiązanych problemów.

— komar
źródło

1

@FrustratedWithFormsDesigner najtrudniej było wymyślić, jak wpisać „oczerniany” na stronie wyszukiwania wyroczni, aby wyniki były filtrowane do „bugs.sun.com”. Reszta była łatwa, właśnie sprawdziłem kilka wyskakujących wyników wyszukiwania. „Denigrate” to całkiem dobre słowo do wyszukiwania :)

— gnat

1

Zobacz, użyłem Google do znalezienia tego pierwszego, ale nie dało mi to innych. Prawdopodobnie powinienem wyglądać mocniej. Dzięki

— Jacob Schoen,

@ jschoen Myślę, że to nie tyle twoja wina; Rozszerzyłem odpowiedź na ten temat

— komara

4

Po dalszych kopaniach udało mi się znaleźć post Joga na blogu o nazwie Deprecation . Zasadniczo stwierdza, że rzeczy oznaczone jako przestarzałe są uważane za szkodliwe do użycia, a niektóre rzeczy są po prostu odradzane.

Ogólna zasada dla kilku wydań funkcji mówi, że podstawowe komponenty JDK są oznaczone jako przestarzałe tylko wtedy, gdy są aktywnie szkodliwe. Jeśli użycie klasy lub metody jest po prostu odradzane, zwykle nie jest to wystarczające, aby zdobyć przestarzały znak.

Wspomniał, że obecnie istnieje sposób, aby oznaczyć przedmiot jako zniechęcony do użycia, ale może w końcu dodać sposób na zrobienie tego.

W pewnym momencie tego rodzaju porady mogą zostać sformalizowane za pomocą mniej szkodliwego niż przestarzałego narzędzia „oczerniania” opartego na kombinacji tagów javadoc i adnotacji, aby umożliwić programowe kontrole użycia tych mniej szkodliwych elementów interfejsu API.

Chociaż nie mogę znaleźć nic innego konkretnie na temat decyzji o użyciu terminu Denigrated, wydaje się to dość bliskie. Na tej podstawie wydaje się, że działanie, które programista powinien podjąć, jest takie samo, jak Przestarzałe , nie używaj tej metody.

— Jacob Schoen
źródło