¿Cómo debo anotar que una clase es inmutable en Java?

14

Recientemente me topé con lo útiles que son los objetos inmutables y que, por ejemplo, si pasa elementos a un constructor y su clase debe ser inmutable, debe copiar estos elementos si no son inmutables.

Esto requiere mucha verificación o conocimiento sobre mi proyecto, porque si tengo

public A(B foo)

y Bno es inmutable, Atendría que copiar B. Ahora imagine Bparece inmutable, pero tiene clases mutables en el constructor y así sucesivamente.

¿Existe algún estándar o práctica recomendada para documentar si una clase es inmutable en Java? Parece que no hay una @immutablepalabra clave en Javadoc.

La anotación @Immutable parece ser algo totalmente diferente para la generación automática de clases y no forma parte de Java estándar.

java documentation immutability Aufziehvogel
fuente
2
En primer lugar, la copia defensiva le permite evitar eso. En segundo lugar, la forma de documentarlo es la clase Javadoc
raptortech97
"la forma de documentarlo es la clase Javadoc" ¿Hay una forma estándar de hacerlo? Entonces esta sería la respuesta aceptada ya.
Aufziehvogel
@ raptortech97 Una de las principales ventajas de las clases inmutables es que no hay necesidad de copia defensiva. Si tiene que haber una copia defensiva de un objeto supuestamente inmutable, lo está haciendo mal.
itsbruce
1
@itsbruce Estaba hablando de copiar objetos mutables. Además, hay una razón para copiar un objeto inmutable: la localidad de caché. Algunos recolectores de basura preservan el orden relativo de los objetos, por lo que los objetos asignados juntos permanecen juntos.
Doval
Tienes razón. Culpa mía.
itsbruce

Respuestas:

7

Mirando la documentación de la Stringclase (el texto en negrita es algo que hice):

La clase String representa cadenas de caracteres. Todos los literales de cadena en programas Java, como "abc", se implementan como instancias de esta clase. Las cuerdas son constantes; sus valores no se pueden cambiar después de que se crean. Los amortiguadores de cadena admiten cadenas mutables. Como los objetos de cadena son inmutables, se pueden compartir.

Como puede ver, no hay un etiquetado particular u otros marcadores, sin embargo, sí especifican en el JavaDoc que describe la clase que la Stringclase representa un objeto constante e inmutable.

Por lo tanto, suponiendo que haya seguido las instrucciones proporcionadas en este tutorial de Oracle para crear una clase inmutable, para asegurarse de que la inmutabilidad de la clase esté documentada, debe asegurarse de mencionar en ella el JavaDoc que describe la clase y qué hace.

Si eso aún no se ajusta a lo que necesita, puede echar un vistazo a cómo podría crear etiquetas JavaDoc personalizadas aquí .

npinti
fuente