Sollte ich JavaDoc-Verfall oder die Annotation in Java verwenden?

81

Derzeit gibt es zwei Möglichkeiten, Code in Java als veraltet zu markieren.

Über JavaDoc

/**
 * @deprecated
 */

Oder als Anmerkung:

@Deprecated

Dies ist mein Problem - ich finde es etwas zu viel, beides zu deklarieren, wenn eine Methode bei Verwendung von Eclipse als veraltet markiert wird. Ich möchte wirklich nur einen von ihnen verwenden.

Gibt die Verwendung der Annotation dem Compiler jedoch tatsächlich nützliche zusätzliche Informationen?

Aber nur unter Verwendung der Anmerkung kann ich nicht angeben, warum die Methode veraltet ist - ich kann dies nur mit JavaDoc tun und eine Methode verwerfen, ohne anzugeben, warum sie schlecht ist.

Kann ich nur einen davon verwenden? Oder sollte ich wirklich nur lernen, beides zu spezifizieren?

java annotations javadoc deprecated corgrath
quelle
4
Was ist, wenn der andere Programmierer Ihre Quellen nicht hat? Er wird nicht wissen, dass Ihre Methode veraltet ist. Ich würde sagen, verwenden Sie Annotation @Deprecated
Eduard
1
@ t-edd: Wenn der andere Programmierer weder über die Quellen noch über die Javadocs verfügt (in denen auch Anmerkungen angezeigt werden), ist die versehentliche Verwendung veralteter APIs das geringste dieser Probleme.
Michael Borgwardt
1
@ Michael Borgwardt Ich habe nur versucht herauszufinden, welche Probleme es bringen könnte. Und dies ist nur eine, die ich mir einfallen lassen könnte. Manchmal können Sie das Herunterladen von Quellen und Javadoc weglassen und veraltete APIs verwenden, die in der nächsten Version nicht vorhanden sind ...
Eduard

Antworten:

76

Sie sollten beide verwenden. Mit der Anmerkung kann der Compiler eine Warnung anzeigen, wenn eine veraltete Methode verwendet wird, und der Javadoc erklärt, warum. Beides ist wichtig.

Gemäß dem Java Annotations- Tutorial von Oracle :

Wenn ein Element veraltet ist, sollte es auch mit dem Tag Javadoc @deprecated dokumentiert werden ...

Rohprogrammierung
quelle
5
Der Oracle-Compiler zeigt jedoch auch eine Warnung für das Javadoc-Tag an, sodass die Anmerkung nicht wirklich benötigt wird.
Michael Borgwardt
@ Michael - in vielen Fällen (aber nicht alles, was ich mir vorstellen würde), kann dies mit@SuppressWarnings("deprecation")
luis.espinal
3
@MichaelBorgwardt Ich verstehe Ihr Denken, aber zu viel davon führt schließlich dazu, dass "Sie sowieso keine Dokumentation schreiben, weil Sie nur dem Quellcode vertrauen können". Die Javadoc-Annotation erfüllt einen Zweck, zum Beispiel ist sie der einzige Ort, an dem der Benutzer angewiesen werden kann, "stattdessen diesen Ersatz zu verwenden".
Edwin Buck
3
Amen Edwin. Die Tatsache, dass 2 Notationen erforderlich sind, ist allerdings scheiße.
ggb667
@MichaelBorgwardt Seit JDK 9 beschwert sich javac, wenn das Javadoc-Tag ohne die Anmerkung verwendet wird. Sinnvoll, da ein anderer Compiler möglicherweise nur die Anmerkung überprüft.
Martin
37

Aus dem Maul des Pferdes :

HINWEIS: In der Java-Sprachspezifikation müssen Compiler Warnungen ausgeben, wenn Klassen, Methoden oder Felder verwendet werden, die mit der Annotation @Deprecated gekennzeichnet sind. Compiler sind in der Java-Sprachspezifikation nicht erforderlich, um Warnungen auszugeben, wenn auf Klassen, Methoden oder Felder zugegriffen wird, die mit dem Tag @deprecated Javadoc gekennzeichnet sind, obwohl die Sun-Compiler dies derzeit tun.

Wenn Sie also garantieren möchten, dass Compiler-Warnungen angezeigt werden, müssen Sie die Anmerkung verwenden. Und wegen der atemberaubenden Inkompetenz einiger API-Designer müssen Sie auch das Javadoc-Tag angeben, um eine Erklärung zu geben.

Persönlich würde ich sagen, dass die Annotation nutzlos ist und weggelassen werden sollte, bis sie behoben ist, da jeder gute Compiler oder jede gute IDE auch Warnungen mit dem Javadoc-Tag anzeigt.

Michael Borgwardt
quelle
3
"Da jeder gute Compiler oder jede gute IDE auch Warnungen mit dem Javadoc-Tag anzeigt." Und jeder anständige Programmierer wird sich nicht darauf verlassen, dass der Compiler ihm von veralteten Dingen erzählt, sondern nach Dokumentation neuer oder geänderter APIs sucht.
Jwenting
12
@jwenting, nach Dokumentation zu suchen, ist Zeitverschwendung für einen Menschen. Lassen Sie die Maschinen herausfinden, ob etwas Alarmierendes vor sich geht, und erzählen Sie Ihnen davon. Das ist ihre Aufgabe.
Thejoshwolfe
2
@jwenting Ich bin anderer Meinung. Anmerkungen und Javadocs sind eine Möglichkeit für den Programmierer, die APIs zu "kennen". Es ist eine gültige Form der Dokumentation. Wann immer möglich, sollte der Programmierer seine / ihre Intelligenz einsetzen, um über interessante Dinge nachzudenken, und nicht um Dokumentation von wem weiß wo zu suchen.
Andres F.
3
@jwenting: OK, aber wie ist die Tatsache, dass eine bestimmte API veraltet ist, Teil der Grundlagen? Und wie weisen Compiler-Warnungen auf die Verwendung veralteter APIs in einem Code-Text hin, der "die Absicht des Programmierers vorhersagt"?
Michael Borgwardt
8
Ich nehme an, das Beste wäre, wenn die Annotation @Deprecated eine Zeichenfolge 'value' unterstützen könnte, die eine Erklärung dafür akzeptieren könnte, warum die Ablehnung vorhanden ist. Die Erklärung scheint der einzige Grund zu sein, warum man den Javadoc-Weg anstelle der Annotation selbst verwenden würde.
Jrharshath
6

Sie sollten beide schreiben. Die @Deprecated Anotation ist für den Compiler und das @deprecated JavaDoc-Tag ist für die Person, die jetzt wissen möchte, warum dies veraltet ist.

Ein Beispiel kann so aussehen:

/**
* @deprecated We dont need this Method because ...
*/
@Deprecated
public void doStuff(){..}
Marcel
quelle
2
Für den Compiler? Dem Compiler ist es egal, Warnungen an den Entwickler zu senden, daher sind beide für den Entwickler. Es ist nur so, dass die Annotation für sich genommen fast nutzlos ist, während die Verwendung des Javadoc-Kommentars nicht garantiert ist. Sun / Oracle (ich weiß nicht, auf wessen Uhr dies war) hat eine Situation eingerichtet, in der Entwickler zwei verschiedene Dinge tun müssen, um die Situation angemessen zu dokumentieren, in der eine hätte ausreichen müssen.
Nasch
Beide Antworten sind genau richtig. Sie sollten beide verwenden, aber nur einen verwenden müssen.
Thonnor
5

Sie sollten beide angeben.

Die Annotation informiert den Compiler darüber und löst Warnungen aus, wenn die Methode verwendet wird. Das JavaDoc-Attribut informiert Entwickler, bevor sie es verwenden.

Das sind zwei sehr unterschiedliche Dinge!

Dunaril
quelle
6
Dies sind überhaupt keine verschiedenen Dinge. Wenn die Anmerkung eine Erklärung als Parameter zulässt, kann dies auch Entwicklern angezeigt werden.
Michael Borgwardt
@ Michael Ihre eigene Antwort betont den Unterschied zwischen ihnen. Eigentlich entwickelt es sich sogar auf der gleichen Idee wie meine.
Dunaril
5
Nein, meine Antwort betont, dass das Javadoc-Tag nur noch benötigt wird, weil die Anmerkung schlecht gestaltet wurde. Anmerkungen sind Code-Metadaten und Informationen für Entwickler, genau wie Methodensignanturen.
Michael Borgwardt
2
2 Tags zu brauchen ist dumm. Die Anmerkung sollte nicht existieren, da sie ohne die Dokumentation so gut wie wertlos ist. Tatsächlich frage ich mich gerade, warum diese besondere Sache als veraltet markiert ist. Es gibt kein @Deprecated Javadoc-Tag, daher habe ich keine Ahnung. Das ist scheiße. Es ist fast schlimmer als nichts, weil irgendwann jemand sagte "benutze es nicht", aber nicht warum. Drang, das Aufstehen zu erwürgen.
ggb667
1

Dies kann leicht mit einer guten IDE behandelt werden.

Eclipse Neon, z. Fügt automatisch die Anmerkung @Deprecated hinzu, wenn ich ein Javadoc @deprecated für eine Methode oder ein Feld erstelle.

Also schreibe ich einfach das Javadoc mit der entsprechenden Erklärung und lasse die IDE sich darum kümmern, die Annotation @Deprecated hinzuzufügen, sobald ich die Datei speichere.

Unmöglich
quelle