External Annotations

If you had worked with IntelliJ IDEA for a while, you’re most likely aware of @Nullable, @NotNull annotations which allow you to formally specify method contracts and validate whether these contracts are met, and @NonNls annotation which is helpful when you want to exclude strings from the internationalization process.

However, there’re several cases when direct annotating code is not advisable: for example, project is shared between team members that use different IDEs, or you work with library classes. That does not mean you can’t make use of these annotations, though — with IntelliJ IDEA you can store annotations outside of the source code.

Let’s have a look at how it works. First, we need to open the Settings dialog (Ctrl + Alt + S) and go to Code Style (F), then check the option Use external annotations at the Code Generation tab. Now, add the annotations.jar library to either module or project. You can find it under INTELLIJ_IDEA_HOME/lib folder.

Adding annotations.jar
After that, open your current inspection profile and make sure Constant conditions& exceptions inspection is enabled and Suggest @Nullable annotation for methods that may possibly return null option is selected.

At this moment we can enjoy externally annotating methods, fields, parameters, etc. For example, we work on a module that contains a method that might return null.

Method that might return null

Let’s add annotation — just click the light bulb. IntelliJ IDEA asks whether we want to add annotation in code directly, or store it externally. Select the second option and specify the external annotation root for the current module.

Note: You only select the location for external annotations once, so each next external annotation within this module will be stored in the same folder. Alternatively, you can specify annotations root at any time: open Project Settings dialog and go to the Modules page, then select the needed module and open its Paths tab. There you can find External annotations area, where you can manage external annotations attached to the module.

Now, this method is annotated without placing anything to the source code directly. You can press Ctrl + Q to view the attached annotation.

Viewing external annotation

With external annotations you can even annotate methods within JDK classes.

Annotating JDK classes

Just like when you add external annotation on the module level, you can specify the storage location right when you add the annotation, or using Project Settings dialog. In the latter case, open Project Settings dialog, go to JDKs and specify the path in the Annotations tab.

This entry was posted in Tips & Tricks. Bookmark the permalink.

6 Responses to External Annotations

  1. alex says:

    That’s great, but how do i get them from maven repository?

  2. Nowaker says:


  3. Nowaker says:

    Ehh, XML is not escaped here. The dependency is:
    groupId: org.jetbrains
    artifactId: annotations
    version: 7.0.2

  4. Sergey says:

    Images are broken

  5. Eric Lambart says:

    I have been searching for the last hour for a simple summary of ALL the annotations included in annotations.jar and annotations-java8.jar, and I can’t find it. This page from 2008 keeps coming up as one of the top results. I’m usually pretty good at googling, so I’m beginning to wonder such a page even exists?

    I also can’t find any clarification of the difference, if any, there is between the two jars (java8 vs the other). For the versions I have, there is a difference in file size of 32 bytes.

Leave a Reply

Your email address will not be published. Required fields are marked *