Javadoc

A comment style that explains what your code does — written for the next person who reads it, who might just be you, later.

/**
 * Counts how many vowels appear in a phrase, ignoring case.
 *
 * @param phrase the text to check
 * @return the number of vowels found
 */
static int solve(String phrase) { ... }

Three Comment Types

Java gives you three ways to leave a note in your code. Each one exists for a different job.

One

Line comment

// checks each vowel one at a time

Starts with //, ends at the end of the line. Good for a quick note on one specific piece of code.

Two

Block comment

/* This whole method works by
   comparing string lengths
   before and after removing
   each vowel. */

Starts with /*, ends with */. Can span multiple lines — good for a longer explanation.

Three

Javadoc comment

/**
 * @param phrase text to check
 * @return vowel count
 */

Starts with /** — one extra star. Sits directly above a method, and can generate real documentation pages automatically.

Javadoc Tags

A Javadoc comment isn't just prose — it uses specific tags that describe a method's pieces individually, so tools (and people) can pull out exactly what they need.

Tag	Describes	Example
@param	one parameter, by name	`@param phrase the text to check`
@return	what comes back, and when	`@return the number of vowels found`
@throws	an exception the method can raise	`@throws NullPointerException if phrase is null`

/**
 * Counts how many vowels appear in a phrase, ignoring case.
 *
 * @param phrase the text to check
 * @return the number of vowels found
 */
static int solve(String phrase) {
    String lower = phrase.toLowerCase();
    int count = 0;
    count += lower.length() - lower.replace("a", "").length();
    count += lower.length() - lower.replace("e", "").length();
    count += lower.length() - lower.replace("i", "").length();
    count += lower.length() - lower.replace("o", "").length();
    count += lower.length() - lower.replace("u", "").length();
    return count;
}

Why comment this one specifically?
The technique — subtracting a modified string's length from the original — isn't obvious just from reading the code. The Javadoc doesn't need to explain how the trick works line by line; that's what an inline // comment is for. It just needs to say what the method does, in case someone's only reading the signature.

Preconditions & Postconditions

Good documentation doesn't just describe what a method does — it describes what has to be true before you call it, and what's guaranteed once it's done.

Term	Means
precondition	what must be true before the method is called, for it to work correctly
postcondition	what's guaranteed to be true after the method finishes

For solve(String phrase) above: the precondition is that phrase isn't null — calling .toLowerCase() on null would crash. The postcondition is that the returned number is never negative, since you can't have fewer than zero vowels.

Before & After

The exact same code, correct either way — but only one version tells you anything before you've read every line.

Before

static String solve(String word) {
    return word.charAt(0) + ""
        + word.charAt(word.length() - 1);
}

After

/**
 * Combines a word's first and
 * last character.
 *
 * @param word the word to shorten
 * @return the first and last
 *         letter, concatenated
 */
static String solve(String word) {
    return word.charAt(0) + ""
        + word.charAt(word.length() - 1);
}