Wie soll ich kommentieren, dass eine Klasse in Java unveränderlich ist?

14

Ich bin kürzlich darauf gestoßen, wie nützlich unveränderliche Objekte sind und dass Sie, wenn Sie z. B. Elemente an einen Konstruktor übergeben und Ihre Klasse unveränderlich sein soll, diese Elemente kopieren müssen, wenn sie selbst nicht unveränderlich sind.

Dies erfordert viel Überprüfung oder Wissen über mein Projekt, denn wenn ich habe

public A(B foo)

und Bist nicht unveränderlich, Aich müsste kopieren B. Stellen Sie sich jetzt vor, dass dies Bunveränderlich ist, aber selbst veränderbare Klassen im Konstruktor usw. hat.

Gibt es einen Standard oder eine bewährte Methode, um zu dokumentieren, ob eine Klasse in Java unveränderlich ist? Es scheint, dass es @immutablein Javadoc kein Schlüsselwort gibt .

Die Annotation @Immutable scheint für die automatische Klassengenerierung etwas völlig anderes zu sein und nicht Teil von Standard-Java.

java documentation immutability Aufziehvogel
quelle
2
Erstens können Sie dies durch defensives Kopieren umgehen. Zweitens ist der Weg, es zu dokumentieren, die Klasse Javadoc
raptortech97
"die Art zu dokumentieren ist die Klasse Javadoc" Gibt es eine Standardmethode, um dies zu tun? Dann wäre dies bereits die akzeptierte Antwort.
Aufziehvogel
@ raptortech97 Einer der Hauptvorteile unveränderlicher Klassen besteht darin, dass kein defensives Kopieren erforderlich ist . Wenn ein angeblich unveränderliches Objekt defensiv kopiert werden muss, machen Sie es falsch.
itsbruce
1
@itsbruce Er sprach über das Kopieren von veränderlichen Objekten. Es gibt auch einen Grund, ein unveränderliches Objekt zu kopieren: die Cache-Lokalität. Einige Garbage Collectors behalten die relative Reihenfolge der Objekte bei, sodass gemeinsam zugewiesene Objekte zusammen bleiben.
Doval
Du hast recht. Mein Fehler.
itsbruce

Antworten:

7

Schauen Sie sich die Dokumentation der StringKlasse an (Fettdruck habe ich gemacht):

Die String-Klasse repräsentiert Zeichenfolgen. Alle Zeichenfolgenliterale in Java-Programmen, z. B. "abc", werden als Instanzen dieser Klasse implementiert. Saiten sind konstant; Ihre Werte können nach ihrer Erstellung nicht mehr geändert werden. String-Puffer unterstützen veränderbare Strings. Da String-Objekte unveränderlich sind, können sie gemeinsam genutzt werden.

Wie Sie sehen, gibt es keine bestimmten Beschriftungen oder andere Markierungen. In JavaDoc wird jedoch angegeben, dass die StringKlasse ein konstantes, unveränderliches Objekt darstellt.

Unter der Annahme, dass Sie die Anweisungen in diesem Oracle-Lernprogramm befolgt haben , um eine unveränderliche Klasse zu erstellen, und um sicherzustellen, dass die Unveränderlichkeit der Klasse dokumentiert ist, sollten Sie nur darauf achten, dass Sie im JavaDoc die Beschreibung der Klasse und deren Inhalt angeben tut.

Wenn das immer noch nicht passt , was Sie brauchen, können Sie einen Blick darauf werfen, wie Sie benutzerdefinierte JavaDoc Tags bauen könnten hier .

npinti
quelle