Comment dois-je annoter qu'une classe est immuable en Java?

14

J'ai récemment découvert l'utilité des objets immuables et que, par exemple, si vous passez des éléments à un constructeur et que votre classe doit être immuable, vous devez copier ces éléments s'ils ne sont pas immuables eux-mêmes.

Cela nécessite beaucoup de vérification ou de connaissances sur mon projet, car si j'ai

public A(B foo)

et Bn'est pas immuable, Aje dois copier B. Imaginez maintenant Bsemble immuable, mais lui-même a des classes mutables dans le constructeur et ainsi de suite.

Existe-t-il une norme ou une meilleure pratique pour documenter si une classe est immuable en Java? Il semble qu'il n'y ait pas de @immutablemot-clé dans Javadoc.

L' annotation @Immutable semble être quelque chose de totalement différent pour la génération de classe automatique et ne fait pas partie de Java standard.

java documentation immutability Aufziehvogel
la source
2
Premièrement, la copie défensive vous permet de contourner cela. Deuxièmement, la façon de le documenter est la classe Javadoc
raptortech97
"la façon de le documenter est la classe Javadoc" Existe-t-il une manière standard de procéder? Alors ce serait déjà la réponse acceptée.
Aufziehvogel
@ raptortech97 L'un des principaux avantages des classes immuables est qu'il n'y a pas besoin de copie défensive. S'il doit y avoir une copie défensive d'un objet prétendument immuable, vous le faites mal.
itsbruce
1
@itsbruce Il parlait de copier des objets mutables. De plus, il y a une raison pour copier un objet immuable - la localisation du cache. Certains ramasse-miettes préservent l'ordre relatif des objets, de sorte que les objets alloués ensemble restent ensemble.
Doval
Tu as raison. Ma faute.
itsbruce

Réponses:

7

En regardant la documentation de la Stringclasse (le texte en gras est quelque chose que j'ai fait):

La classe String représente des chaînes de caractères. Tous les littéraux de chaîne dans les programmes Java, tels que "abc", sont implémentés en tant qu'instances de cette classe. Les chaînes sont constantes; leurs valeurs ne peuvent pas être modifiées après leur création. Les tampons de chaîne prennent en charge les chaînes mutables. Les objets String étant immuables, ils peuvent être partagés.

Comme vous pouvez le voir, il n'y a pas d'étiquetage particulier ou d'autres marqueurs, cependant, ils spécifient dans le JavaDoc décrivant la classe que la Stringclasse représente un objet constant et immuable.

Ainsi, en supposant que vous avez suivi les instructions fournies dans ce didacticiel Oracle pour créer une classe immuable, pour vous assurer que l'immuabilité de la classe est documentée, vous devez simplement vous assurer que vous y mentionnez le dans le JavaDoc décrivant la classe et ce qu'elle Est-ce que.

Si cela ne correspond toujours pas à vos besoins, vous pouvez voir comment vous pouvez créer des balises JavaDoc personnalisées ici .

npinti
la source