Was ist der beste Weg, um eine veraltete Klasse in Java zu kommentieren?

11

Ich möchte wissen, wie ich am besten einen Kommentar hinzufügen kann, um eine veraltete Klasse in Java zu identifizieren. Sollte ich den vorherigen Kommentar entfernen, der oben in der Klasse hinzugefügt wurde, damit ein anderer Programmierer weiß, wofür diese Klasse gedacht war, oder sollte ich ihn unterhalb des Kommentars hinzufügen?

java code-quality api comments alculete
quelle

Antworten:

17

Der empfohlene Ansatz zum Verwerfen einer Klasse, Methode oder eines Felds in Java besteht darin, die @DeprecatedAnnotation zu verwenden, die in Java 5 verfügbar wurde, oder das @deprecatedJavaDoc-Tag, das es seit Java 1.1 gibt. Oracle verfügt über ein Dokument mit Einzelheiten dazu, wie und wann APIs verworfen werden sollen , die als relevant erscheinen.

Sollte ich den vorherigen Kommentar entfernen, der oben in der Klasse hinzugefügt wurde, damit ein anderer Programmierer weiß, wofür diese Klasse gedacht war, oder ihn unterhalb des Kommentars hinzufügen?

Sie sollten keine vorhandenen Kommentare bearbeiten oder entfernen, außer das JavaDoc-Tag oder die Annotation hinzuzufügen. Veralteter Code wird möglicherweise noch in Legacy-Systemen verwendet, und Entwickler dieser Systeme müssen Zugriff auf die Dokumentation haben, die die ursprünglichen Entwickler in irgendeiner Form erstellt haben.

Thomas Owens
quelle
1
+1: Wenn Sie die @ Depricated-Annotationen verwenden, erhalten Sie auch IDEs wie Eclipse die Möglichkeit, diese Methode zu streichen und Entwicklern andere visuelle Hinweise zu geben.
Ryan Hayes
Ja, ich weiß, wie man veraltet und die Annotation verwendet. Meine Frage ist zum Beispiel, dass ich diesen Code / ** * Kommentar zur Klasse ** / public class ClassToDeprecate {// Code hier} habe, sollte ich den Kommentar entfernen und so sein
Alculete
1
@Spammer Der Artikel, auf den ich verlinkt habe, diskutiert das. Das Durchsuchen der Java-API-Dokumentation beantwortet dies ebenfalls. Das einzige, was Sie tun sollten, ist die @DeprecatedAnmerkung oder das @deprecatedJavaDoc-Tag hinzuzufügen. Das war's - sonst nichts, nichts mehr.
Thomas Owens
Übrigens
1
Durch Hinzufügen von @deprecatedJavaDoc-Tag und -Beschreibung zusammen mit @DeprecatedAnmerkungen wird mehr Aufschluss darüber gegeben, warum es veraltet war. Es wäre also vorteilhafter, beide zu verwenden, als nur @DeprecatedAnmerkungen.
WarFox