Java Explain Intent with Comments

Understand the idea

Use // for a short comment and /* ... */ for a block comment. Documentation comments beginning with /** can describe a public API and be processed by javadoc. Comments are not executable instructions, so an outdated comment can disagree with code without a compiler warning. Prefer meaningful names for obvious facts and reserve comments for reasoning, assumptions or a necessary warning about a boundary.

Run it locally

Use a local JDK 21 or newer. Save the complete example as Main.java in a separate lab folder, then compile and run it with the commands below. Java examples do not run in Bhylu’s browser playground. The -ea option enables assertion checks used by some lessons.

JDK and terminal setup

javac --release 21 -encoding UTF-8 -d out Main.java
java -ea -cp out Main

A worked example

public class Main {
    public static void main(String[] args) {
        // Keep two places free for accessibility needs.
        int publicCapacity = 18 - 2;
        System.out.println(publicCapacity);
    }
}

Expected output

16

The subtraction is easy to read on its own. The comment contributes the policy behind the subtraction, which matters if the room capacity changes. If the policy is used in several places, give it a named constant or a small policy method rather than copying the same subtraction and comment into multiple files.