Comments and Documentation in Java

Think about a note you have seen beside a piece of writing. It might be a footnote explaining the background of a historical event, or a pencil mark in the margin of a textbook reminding you why a passage mattered. Neither note is part of the main writing, yet both exist to help you understand that writing. This article uses that everyday idea to explain how programs carry explanatory material alongside their code, and how Java extends that idea in a powerful way.

The source uses the footnote in an old novel as an illustration. The footnote explains the historical background of an event the author mentioned, but it is not part of the story. Reading the story without the footnote still gives you the story. Reading the footnote gives you more understanding of it. The annotation sits beside the text, and it changes how you understand the text without changing the text itself.

Programs already contain a familiar form of annotation. A comment in a program is a kind of annotation: it is metadata written about the code, placed alongside it, and meant to explain what the code means to a human reader.

Comments are not the only form of metadata a program can carry. The source makes this point directly: comments are only one type of metadata that might be added to programs. That raises a natural question. If comments are not the whole story, what else can be added to a program, and who decides what counts?

Follow a single source file through the compiler. The file contains two kinds of material written about the code: ordinary comments and annotations. The diagram below shows what happens to each one. The compiler discards comments, so they do not reach the compiled output. Annotations pass through the compiler and are carried forward, which is what allows them to be used after compilation.

Read the diagram from top to bottom. Both comments and annotations start in the same source file. At the compiler, the comment path ends, because the compiler ignores it. The annotation path continues, so the compiled output still holds the annotation. This is the difference that matters: a comment is written for a human reader and is thrown away, while an annotation can be read by a program later.

Java 5.0 introduced a feature called annotations into the Java language. Its purpose was to make it easier to create new kinds of metadata for Java programs. Before this feature, the metadata a programmer could attach to a program was limited to what the language already offered. With annotations, the programmer can devise new ways of annotating a program.

The reason programmers wanted this feature follows from that change. A fixed set of metadata types limits what a program can describe about itself. Annotations let a programmer invent a kind of metadata suited to the program's own needs and then write other programs that read it and act on it.

A comment is written for a human reader and is discarded by the compiler. A Java annotation can be read by a program, and that program can act on what it finds. The source describes this with Javadoc comments: a documentation program processes them to create API documentation. The Java annotation feature generalizes that possibility, so programmers can define their own kinds of metadata for programs to read.

The sequence runs in order. The programmer compiles the source. The compiler keeps the annotation and drops ordinary comments. Later, a separate reading program looks into the compiled output, finds the annotation, and uses it. The source confirms the core idea that a program can read and use these annotations; the exact mechanics of how a reading program locates them are beyond what this article covers.

The two kinds of material differ in who reads them and whether the compiler keeps them. The comparison below groups the features of an ordinary comment and of the Java annotation feature side by side.

Both are metadata written about a main text. The difference is the audience and the outcome. An ordinary comment serves only a human reader and has no effect on the program. A Java annotation can serve a human reader and also a program that reads it and acts on it.