I recently stumbled upon how useful immutable objects are and that e.g. if you pass elements to a constructor and your class should be immutable, you have to copy these elements if they are not immutable themselves.

This requires a lot of checking or knowledge about my project, because if I have

public A(B foo)

and B is not immutable, A I'd have to copy B. Now imagine B seems immutable, but itself has mutable classes in the constructor and so on.

Is there a standard or best-practice for documenting if a class is immutable in Java? It seems there is no @immutable keyword in Javadoc.

The @Immutable annotation seems to be something totally different for auto class generation and not part of standard Java.

  • 2
    Firstly, defensive copying allows you to get around that. Secondly, the way to document it is the class Javadoc Feb 5, 2015 at 12:21
  • "the way to document it is the class Javadoc" Is there a standard way of doing this? Then this would be the accepted answer already. Feb 5, 2015 at 12:25
  • @raptortech97 One of the major advantages of immutable classes is that there is no need for defensive copying. If there has to be defensive copying of an allegedly immutable object, you are doing it wrong.
    – itsbruce
    Feb 5, 2015 at 12:43
  • 1
    @itsbruce He was talking about copying mutable objects. Also, there is one reason to copy an immutable object - cache locality. Some garbage collectors preserve the relative ordering of objects, so objects allocated together stay together.
    – Doval
    Feb 5, 2015 at 12:50
  • You're right. My bad.
    – itsbruce
    Feb 5, 2015 at 12:51

2 Answers 2


Looking at the documentation of the String class (bold text is something I did):

The String class represents character strings. All string literals in Java programs, such as "abc", are implemented as instances of this class. Strings are constant; their values cannot be changed after they are created. String buffers support mutable strings. Because String objects are immutable they can be shared.

As you can see, there is no particular labeling or other markers, however, they do specify in the JavaDoc describing the class that the String class represents a constant, immutable object.

Thus, assuming that you followed the instructions provided in this Oracle tutorial to create an immutable class, to make sure that the immutability of the class is documented, you should just make sure you mention in it the in the JavaDoc describing the class and what it does.

If that still does not suit what you need, you could take a look at how you could build custom JavaDoc tags here.


You can use annotations:

@javax.annotation.concurrent.Immutable from JSR-305

or @net.jcip.annotations.Immutable from Java Concurrency In Practice

  • 3
    Which one of these two is better/recommended?
    – Tautvis
    Jun 17, 2015 at 18:02

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.