Documentation with
Comments

Learn how to write clear, professional documentation in Java using single-line comments, multi-line comments, and Javadoc to make your code readable, maintainable, and exam-ready.

AP Computer Science A

What Are Comments?

Comments are human-readable annotations inserted into source code that the Java compiler completely ignores. They exist solely for programmers: to explain what code does, why a design choice was made, and how to use a class or method correctly.

Why Documentation Matters

Readability

Other programmers (and your future self) can understand your intent without deciphering every line.

Maintainability

Well-documented code is far easier to debug, update, and extend over the lifetime of a project.

AP Exam Credit

The AP CS A free-response rubric awards points for clear preconditions, postconditions, and intent.

Three Types of Java Comments

Single-Line Comments: //

Everything after // on the same line is ignored by the compiler. Use these for quick, targeted annotations directly next to the code they explain.

// Calculate the area of a circle
double area = Math.PI * radius * radius;

int maxScore = 100;  // AP exam max points

Multi-Line Comments: /* ... */

Multi-line comments begin with /* and end with */. Everything between those markers is ignored, even if it spans dozens of lines.

/*
 * This method uses the Euclidean algorithm
 * to find the greatest common divisor of
 * two positive integers a and b.
 */
public static int gcd(int a, int b) {
    while (b != 0) {
        int temp = b;
        b = a % b;
        a = temp;
    }
    return a;
}

Javadoc Comments: /** ... */

Javadoc comments start with /** and use special tags like @param, @return, and @throws. The javadoc tool generates HTML documentation from them.

/**
 * Calculates the average of an array of scores.
 *
 * @param scores  array of integer test scores
 * @return        the mean as a double
 * @throws IllegalArgumentException if array is empty
 */
public static double average(int[] scores) {
    // implementation here
}

// vs /* */ vs /** */

Feature	// Single	/* Multi */	/** Javadoc */
Scope	One line	Any span	Any span
Nestable?	N/A	No	No
Tags (@param)	No	No	Yes
Generates HTML	No	No	Yes
Best for	Quick notes	Block disabling	API docs

Essential Javadoc Tags

1

@param name description: Documents each parameter the method accepts and what it represents.

2

@return description: Describes the value the method returns and its meaning.

3

@throws ExceptionType reason: Declares which exceptions may be thrown and under what conditions.

4

@author name: Identifies the author of a class (used in class-level Javadoc only).

Preconditions & Postconditions

Precondition

A condition that must be true before a method is called. Documented so the caller knows what is required.

Postcondition

A condition guaranteed to be true after a method completes, assuming preconditions were met.

/**
 * Returns the element at the given index.
 *
 * Precondition:  0 ≤ index < list.size()
 * Postcondition: list is unchanged
 *
 * @param index  position of the desired element
 * @return       the element at the specified position
 */

How to Write Great Comments

1

Explain WHY, not WHAT. Avoid restating code literally. Focus on intent and design decisions.

2

Use Javadoc for public APIs. Every public class, method, and constructor should have a /** */ comment.

3

State preconditions and postconditions. Clarify what must be true before and after execution.

4

Keep comments current. When you change code, update the corresponding comment immediately.

5

Be concise. One clear sentence beats a rambling paragraph. Respect the reader's time.

Example 1: Simple Method

/**
 * Determines whether a given integer is even.
 *
 * @param n  the integer to check
 * @return   true if n is divisible by 2, false otherwise
 */
public static boolean isEven(int n) {
    return n % 2 == 0;  // modulo check
}

Example 2: Class-Level Javadoc

/**
 * Represents a student in a gradebook system.
 * Stores the student's name and list of scores,
 * and provides methods for computing statistics.
 *
 * @author Jane Smith
 */
public class Student {

    private String name;
    private ArrayList<Integer> scores;

    /**
     * Constructs a Student with the given name
     * and an empty score list.
     *
     * @param name  the student's full name
     */
    public Student(String name) {
        this.name = name;
        scores = new ArrayList<>();
    }
}

Example 3: Complex Method with Preconditions

/**
 * Returns the index of the maximum value in
 * the specified portion of the array.
 *
 * Precondition:  0 ≤ start < end ≤ arr.length
 * Postcondition: arr is unchanged
 *
 * @param arr    the array to search
 * @param start  inclusive start index
 * @param end    exclusive end index
 * @return       index of the maximum element
 */
public static int maxIndex(int[] arr,
        int start, int end) {
    int idx = start;
    for (int i = start + 1; i < end; i++) {
        if (arr[i] > arr[idx]) {
            idx = i;
        }
    }
    return idx;
}

Common Mistakes

✕ Restating Code

Writing // add 1 to x above x++; adds no value. Explain why you increment instead.

✕ Stale Comments

Changing code without updating its comment creates misleading documentation that is worse than none at all.

✕ Missing Javadoc

Omitting @param and @return tags on public methods forces callers to read the implementation to understand usage.

Quick Reference Guide

Situation	Comment Type	Example Tag/Style
Brief note on a line	// single-line	// handles edge case
Disable a code block	/* multi-line */	/* ... old logic ... */
Method documentation	/** Javadoc */	@param, @return
Class documentation	/** Javadoc */	@author
Contract specification	/** Javadoc */	Precondition / Postcondition

Question 1 of 5

Which comment syntax is specifically designed to generate HTML documentation in Java?

Only /** Javadoc */ comments are processed by the javadoc tool to produce HTML API documentation. The other two are ignored by all tools except the compiler.

Question 2 of 5

A precondition in a method's documentation describes:

A precondition states what must be true before the method executes: valid parameter ranges, non-null references, and so on. The postcondition describes what is true after execution.

Question 3 of 5

Consider the following Javadoc comment:

/**
* Removes and returns the last element.
*
* @param list the list to modify
* @return the removed element
*/

The method signature is:
public static String removeLast(ArrayList<String> list)

▼ Tap to read passage

Which of the following is missing from this documentation?

The comment has a description, @param, and @return. However, calling removeLast on an empty list would cause an error. The precondition "list is not empty" is missing and should be documented.

Question 4 of 5

Which of the following is an example of a poor comment?

"// set x to 5" merely restates the code x = 5; without adding insight. Good comments explain why a value is chosen or what it represents, not just what the code literally does.

Question 5 of 5

In Java, which of the following is true about multi-line comments?

Multi-line comments start with /* and end at the first */ the compiler finds. They cannot be nested: a second /* inside is treated as plain text, and the first */ closes the entire comment.

Documentation withComments

What Are Comments?

Why Documentation Matters

Three Types of Java Comments

Single-Line Comments: //

Multi-Line Comments: /* ... */

Javadoc Comments: /** ... */

// vs /* */ vs /** */

Essential Javadoc Tags

Preconditions & Postconditions

How to Write Great Comments

Example 1: Simple Method

Example 2: Class-Level Javadoc

Example 3: Complex Method with Preconditions

Common Mistakes

Quick Reference Guide

Question 1 of 5

Question 2 of 5

Question 3 of 5

Question 4 of 5

Question 5 of 5

Documentation with
Comments