Metadata and Program Structure

An annotation is metadata, or metatext, written about a main text rather than as part of it.

Programming

A Footnote Beside the Story

Picture an old novel with a footnote at the bottom of a page. The footnote explains the historical background of an event the author mentioned. It is not part of the story, yet it helps you understand the story better. Now picture a note you wrote in the margin of your own textbook so you would remember why a passage mattered. Both are notes that sit beside a text and exist to help you understand or appreciate it. Neither one changes the story. This article uses that same idea to explain how programs carry information about themselves, and then how a Java program is put together so that the computer knows where to begin.

Main Text and the Notes Written About It

Definition

An annotation is metadata, or metatext, written about a main text rather than as part of it.

The important move is to separate two things. The main text carries the content. The annotation carries information about that content, such as context, explanation, or a reminder for a reader. Once you see that split, the rest of the material becomes a matter of applying it to programs. A program is a main text, and any note written about the program is an annotation on it.

Key point

Ask two questions of any piece of writing: does this carry the content itself, or does it describe the content? Notes that describe the content are annotations.

Comments as Ignored Annotations

Programs already contain a familiar form of annotation. A comment is metadata written about the code, placed alongside it, and meant to explain what the code means to a human reader. Because the compiler ignores comments, a comment has no effect on what the program does. Removing every comment would change how easy the program is to read, but not how it behaves.

java

// This comment explains the program to a human reader.
// The compiler discards it and it has no effect on the output.
public class Greeting {
    public static void main(String[] args) {
        System.out.println("Hello");
    }
}

// This comment explains the program to a human reader.
// The compiler discards it and it has no effect on the output.
public class Greeting {
    public static void main(String[] args) {
        System.out.println("Hello");
    }
}

Output

Hello

Notes on the code

The two // lines are comments, which are annotations written about the code
Deleting them would leave the printed output unchanged

Comments are only one type of metadata that a program might carry. That observation leads to the next question: if comments are not the whole story, what else can be added to a program, and who decides what it means?

What Java 5.0 Annotations Added

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 was limited to what the language already offered. With annotations, the programmer can devise new ways of annotating a program and then write programs that read and use those annotations.

Feature	Ordinary comment	Java annotation
Who reads it	A human reader	A human reader, and also a program that processes it
What the compiler does with it	Ignores it	Can be processed by tools and programs
Who defines its kind	Free-form text	The programmer can define new kinds of metadata
Example from the source	Explanatory note in code	Javadoc comments processed to create API documentation

Comments and Java annotations differ in whether a program can act on them.

Javadoc comments are the existing example in this course: a documentation program processes them to create API documentation. The annotation feature generalizes that possibility, so that programmers are not limited to the kinds of metadata that already exist.

Tracing an Annotation Through Compilation

A comment stops at the compiler, which discards it. An annotation of the Java 5.0 kind is different: it is meant to be read later by a program. The diagram below traces the path. The annotation starts in the source code, passes through the compiler, is carried into the class file, and can then be read by another program that uses it.

Where does an annotation go when the program is compiled, and how does another program get it later?

Anatomy of a Java Source File

A Java program is built inside a class. The class provides the outer structure, and a subroutine named main provides the starting point for execution. The diagram shows what can sit inside a Java source file and how the parts nest. Only the class and its main method are required for a program to run; the other parts are optional.

What contains what in a Java source file, and which parts are optional versus required?

The Required main Method

The main method is the entry point called by the Java interpreter. In standard Java, its header is written as public static void main(String[] args). The diagram labels each part of that header. The source requires that main be defined in the required form; the individual words are the standard Java spelling of that form.

Which parts of the main method signature are required, and what does each part mean?

java

public class Greeting {
    public static void main(String[] args) {
        System.out.println("Program started");
    }
}

public class Greeting {
    public static void main(String[] args) {
        System.out.println("Program started");
    }
}

Output

Program started

Notes on the code

The class Greeting is the outer structure of the program
The main method is the starting point the interpreter calls
The statement inside main is the only action this program performs

How the Interpreter Starts Execution

When the program runs, the Java interpreter does not begin with the first line of the file. It begins with the main method. Step through the sequence below to see how a run begins.

1
The interpreter starts with the class that defines the program.
2
It locates the subroutine named main inside that class.
3
It calls main, which is the entry point of execution.
4
Execution then proceeds through the statements inside main, in order.

Statements Inside main Set the Order

Statements inside main are executed when the program runs. Their written order is the order in which the actions happen. Each statement finishes before the next one begins. The program below has two print statements. Before reading the output, predict what it will print.

java

public class Order {
    public static void main(String[] args) {
        System.out.println("Hello");
        System.out.println("Goodbye");
    }
}

public class Order {
    public static void main(String[] args) {
        System.out.println("Hello");
        System.out.println("Goodbye");
    }
}

Output

Hello
Goodbye

Notes on the code

The first statement inside main runs first
The second statement runs only after the first has finished

What do you think happens?

Which line prints first when this program runs?

Hello
Goodbye
They print at the same time

Reveal answer

Answer:

Hello prints first, then Goodbye

Statements inside main execute in the order they are written, so the first println runs before the second.

Worked example

Tracing a three-statement main

A main method contains three print statements that print one, two, and three in that order. In what order do the actions happen, and what is the final printed output?

1
Find the entry point
The interpreter calls main, so execution begins at the first statement inside it.
2
Run the first statement
The first statement prints one, and nothing after it runs yet.
3
Run the second statement
The second statement prints two, because it comes after the first.
4
Run the third statement
The third statement prints three, and main then finishes.

Result

The actions happen in written order, and the output is one, then two, then three.

Mistakes Beginners Make with Program Structure

Common mistake
Believing that a comment will run as an instruction
What it looks like
```
// print the total here, placed above a statement
```
Why it fails
A comment is metadata written about the code. The compiler ignores comments, so they have no effect on what the program does.
Do this instead
Treat comments as notes for a human reader. Put the instructions that must run inside main.
Common mistake
Thinking the class is the thing that runs
What it looks like
Looking for the first line of the class body to execute
Why it fails
The class provides the outer structure. The interpreter starts execution at the main method.
Do this instead
Locate main first, then follow its statements in order.
Common mistake
Treating optional parts as required
Why it fails
Package declarations, imports, variable declarations, and other subroutines are optional. The required pieces are the class that contains main and the main method itself.
Do this instead
When reading a file, check for the class and main first. Then identify which optional parts are present.
Common mistake
Assuming an annotation changes program behavior the way a statement does when no tool reads it

Practice Tracing a Small Program

EASY

Given a class named Trace whose main method contains three statements that print Start, Middle, and End in that order, and a comment placed above the first statement, state (a) what the interpreter calls first, (b) the order of the printed output, and (c) whether the comment changes the output.

Hints

Start by identifying the entry point the interpreter calls.
Follow the statements inside main in the order they are written.
Recall why the compiler ignores comments.

Your attempt (not saved)

Key Takeaways

An annotation is metadata, or metatext, written about a main text rather than as part of it; comments are one familiar kind of annotation that the compiler ignores.
Java 5.0 added annotations so programmers can create new kinds of metadata and write programs that read and use it, unlike ordinary comments.
A Java program is defined by a public class that contains a main method, which is the entry point the interpreter calls.
Package declarations and imports are optional; statements inside main execute in the order they are written.

A Footnote Beside the Story

Main Text and the Notes Written About It

Comments as Ignored Annotations

What Java 5.0 Annotations Added

Tracing an Annotation Through Compilation

Anatomy of a Java Source File

The Required main Method

How the Interpreter Starts Execution

Statements Inside main Set the Order

Mistakes Beginners Make with Program Structure

Practice Tracing a Small Program

Key Takeaways

Related Topics