{"title":"Comments","description":"","content":"Comments are notes the compiler ignores but humans read. Java gives you three flavors: single-line, multi-line, and Javadoc. This lesson covers how each one is written, when to use them, and a few habits that keep comments useful instead of turning them into clutter.\n\n---\n\n# The Three Styles\n\nJava supports three comment styles. Two are for notes to other developers, and the third doubles as machine-readable documentation.\n\n\n```java\npublic class Cart {\n // Single-line: ends at the newline\n private double subtotal;\n\n /*\n Multi-line: starts with slash-star,\n ends with star-slash. Useful for longer notes.\n */\n private int itemCount;\n\n /**\n * Javadoc: starts with slash-star-star.\n * Tools like `javadoc` read these to generate HTML docs.\n */\n public double getSubtotal() {\n return subtotal;\n }\n}\n```\n\n\nThe compiler strips all three out before producing bytecode, so comments have zero runtime cost. The difference is in tooling: the `javadoc` tool only reads the third style.\n\nA side-by-side summary:\n\n\n| Style | Syntax | Spans | Used For |\n| ----------- | ------------------------------------- | ---------- | --------------------------------------------------- |\n| Single-line | `// note` | One line | Short inline notes, explaining a tricky expression |\n| Multi-line | `/* note */` | Many lines | Block notes, file headers, longer explanations |\n| Javadoc | `/** note */` before class/method/field | Many lines | API documentation extracted by the `javadoc` tool |\n\n\nThe rest of the lesson walks through each style in detail, then looks at when comments help versus when they get in the way.\n\n---\n\n# Single-Line Comments\n\nA single-line comment starts with `//` and ends at the next newline. Anything between the `//` and the line break is ignored by the compiler.\n\n\n```java\npublic class CartTotal {\n public static void main(String[] args) {\n // Price in USD\n double itemPrice = 29.99;\n int quantity = 3;\n\n double subtotal = itemPrice * quantity; // multiply price by count\n System.out.println(\"Subtotal: $\" + subtotal);\n }\n}\n```\n\n\nA few details:\n\n- `//` can appear at the start of a line or after code. When it follows code, it's called a trailing comment.\n- The comment stops at the newline. The next line is code again, even if it looks visually connected.\n- You can stack many single-line comments to form a block, though `/* ... */` is usually cleaner for that.\n\n---\n\n# Multi-Line Comments\n\nA multi-line comment starts with `/*` and continues until the matching `*/`. Everything in between, including newlines, is ignored.\n\n\n```java\npublic class ProductInfo {\n public static void main(String[] args) {\n /*\n This program prints info about a single product.\n We'll expand it later to read from a catalog file.\n */\n String productName = \"Wireless Headphones\";\n double price = 79.99;\n\n System.out.println(productName + \" - $\" + price);\n }\n}\n```\n\n\nMulti-line comments don't need a `*` on every line, but many developers add one out of habit because it aligns nicely:\n\n\n```java\n/*\n * File: Cart.java\n * Purpose: Holds items added by a customer.\n */\n```\n\n\nThat's just convention. The compiler only cares about the opening `/*` and the closing `*/`.\n\n### Multi-Line Comments Don't Nest\n\nYou can't put a multi-line comment inside another multi-line comment. The compiler matches the first `*/` it sees against the opening `/*` and treats anything after that as code.\n\n**What's wrong with this code?**\n\n\n```java\npublic class NestedComment {\n public static void main(String[] args) {\n /*\n Outer comment opens here.\n /* Inner comment opens here. */\n Outer comment was supposed to close here. */\n System.out.println(\"done\");\n }\n}\n```\n\n\nThe compiler reads it like this: the outer `/*` opens a comment, and the first `*/` (after \"Inner comment opens here.\") closes it. The text \"Outer comment was supposed to close here.\" is then read as code, and `*/` at the end is a syntax error. You get something like:\n\n\n```shell\nNestedComment.java:5: error: illegal start of expression\n Outer comment was supposed to close here. */\n ^\n```\n\n\n**Fix:** Don't nest. Use a single block, or comment out code line by line:\n\n\n```java\npublic class NestedComment {\n public static void main(String[] args) {\n /*\n Outer comment with notes about everything.\n No inner block comments allowed.\n */\n System.out.println(\"done\");\n }\n}\n```\n\n\nIf you want to temporarily disable a block of code that already contains comments, most IDEs let you press a shortcut (Ctrl+/ in IntelliJ) to add `//` to every line, which sidesteps the nesting problem.\n\n---\n\n# Javadoc Comments\n\nA Javadoc comment starts with `/**` (two stars after the slash) and ends with `*/`. It lives immediately above a class, method, or field declaration and describes that element.\n\nA `Cart` class with Javadoc on the class and on each method:\n\n\n```java\n/**\n * Represents a shopping cart that holds items added by a customer.\n * The cart tracks a subtotal and an item count, and can compute a\n * total that includes sales tax.\n *\n * @author Alex\n * @since 1.0\n */\npublic class Cart {\n\n /** Subtotal in USD, before tax. */\n private double subtotal;\n\n /** Number of items currently in the cart. */\n private int itemCount;\n\n /**\n * Adds an item to the cart and updates the subtotal.\n *\n * @param itemPrice price of the item in USD, must be non-negative\n * @param quantity number of units to add, must be positive\n * @throws IllegalArgumentException if itemPrice is negative or quantity is not positive\n */\n public void addItem(double itemPrice, int quantity) {\n if (itemPrice < 0 || quantity <= 0) {\n throw new IllegalArgumentException(\"invalid price or quantity\");\n }\n subtotal += itemPrice * quantity;\n itemCount += quantity;\n }\n\n /**\n * Returns the cart total including a flat sales tax.\n *\n * @param taxRate tax rate as a decimal, for example 0.08 for 8 percent\n * @return total in USD, rounded to two decimal places\n * @see #addItem(double, int)\n */\n public double getTotal(double taxRate) {\n // Round to cents to avoid showing fractions like $12.345\n // We round half-up because that matches what receipts usually show.\n double raw = subtotal * (1 + taxRate);\n return Math.round(raw * 100.0) / 100.0;\n }\n}\n```\n\n\nThe Javadoc on `getTotal` describes the contract (what the method does, what the parameters mean, what it returns) while the regular `//` comments inside the method describe an implementation detail (why we round the way we do). Both are useful, but they serve different readers.\n\n### Standard Javadoc Tags\n\nJavadoc tags start with `@` and add structured information. The most common ones:\n\n\n| Tag | Used On | Meaning |\n| ------------- | ------------------------ | ------------------------------------------------------ |\n| `@param` | Methods, constructors | Describes one parameter |\n| `@return` | Methods | Describes what the method returns |\n| `@throws` | Methods, constructors | Describes an exception the method may throw |\n| `@author` | Classes, interfaces | Names the author |\n| `@since` | Any element | Version when the element was added |\n| `@see` | Any element | Cross-reference to a related class or method |\n| `@deprecated` | Any element | Marks the element as discouraged, with a reason |\n\n\nOrder matters by convention: `@param` tags come first (one per parameter, in declaration order), then `@return`, then `@throws`, then everything else. The `javadoc` tool sorts and groups them in the generated HTML.\n\nA `Customer` class that uses `@deprecated` to mark an old field:\n\n\n```java\n/**\n * A customer of the online store.\n *\n * @since 1.0\n */\npublic class Customer {\n /** Customer's full name. */\n private String name;\n\n /** Customer's email, used for order confirmations. */\n private String email;\n\n /**\n * Customer's mailing address as a single string.\n *\n * @deprecated As of 2.0, use {@link #shippingAddress} which is structured.\n * This field will be removed in 3.0.\n */\n @Deprecated\n private String address;\n\n /** Structured shipping address introduced in 2.0. */\n private String shippingAddress;\n}\n```\n\n\nThe `@deprecated` Javadoc tag explains *why* the element is discouraged and points readers to the replacement. The `@Deprecated` annotation right above it (no `javadoc` involved) is what makes the compiler warn callers. They're a pair: the tag explains, the annotation enforces.\n\n---\n\n# The `javadoc` Command\n\nJavadoc comments aren't just notes for readers of the source code. The JDK ships with a `javadoc` command-line tool that scans `.java` files, pulls out the `/** ... */` blocks, and generates a set of HTML pages that look like the official API docs you see on `docs.oracle.com`. Run it on a source file and the tool writes browsable documentation into an output folder, ready to share or host. Java doesn't bundle a documentation generator into the language itself the way some others do, but `javadoc` is the de-facto standard, and almost every library you'll use was documented with it.\n\nThe flow looks like this:\n\n\n```mermaid\nflowchart LR\n A[Cart.java
with Javadoc
comments]:::cyan --> B[javadoc
command]:::orange\n B --> C[index.html
+ HTML pages]:::teal\n C --> D[Browser
API docs]:::green\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n```\n\n\nA minimal invocation looks like this:\n\n\n```shell\njavadoc -d docs Cart.java\n```\n\n\nThat reads `Cart.java`, writes HTML into a folder named `docs`, and you open `docs/index.html` in a browser to see the result. Open the standard library docs at `docs.oracle.com/en/java/javase/` and you're looking at the exact same kind of output, generated from Javadoc comments in the JDK source.\n\n---\n\n# When Comments Help (and When They Hurt)\n\nGood comments explain *why*. Bad comments restate *what*. The code already shows the *what*, so a comment that just repeats it adds noise without adding information.\n\nCompare the two versions of the same method:\n\n\n```java\npublic class CartTotal {\n\n // Noise comment: tells you nothing the code doesn't already say\n public static double getTotalNoise(double subtotal, double taxRate) {\n // multiply subtotal by 1 plus taxRate\n double raw = subtotal * (1 + taxRate);\n // round raw times 100 then divide by 100\n return Math.round(raw * 100.0) / 100.0;\n }\n\n // Good comment: explains the non-obvious decision\n public static double getTotalGood(double subtotal, double taxRate) {\n double raw = subtotal * (1 + taxRate);\n // Round to cents using half-up. Receipts show two decimals,\n // and Math.round() rounds half-up by default, which matches\n // what the finance team expects on invoices.\n return Math.round(raw * 100.0) / 100.0;\n }\n\n public static void main(String[] args) {\n System.out.println(getTotalGood(89.97, 0.08));\n }\n}\n```\n\n\nThe first version's comments restate the operators. Any reader can see `subtotal * (1 + taxRate)`, so writing \"multiply subtotal by 1 plus taxRate\" is filler. The second version's comment explains the *decision*: why we round, which rounding mode we picked, and why it matches a business expectation. That's information the code can't carry on its own.\n\nUseful comments tend to cover:\n\n- **Why a decision was made.** \"We round half-up to match invoices.\"\n- **Non-obvious edge cases.** \"Quantity zero is allowed for placeholder items in promotions.\"\n- **Intent or contract.** Javadoc telling callers what to pass and what they'll get back.\n- **Workarounds.** \"Old orders have null shipping addresses; we treat null as 'pickup in store'.\"\n- **Pointers to context.** A link to a ticket or a section of a spec that explains a strange branch.\n\nComments that hurt more than they help:\n\n- **Restating the code.** `// increment count` above `count++`. The code says it already.\n- **Stale comments.** A comment that described the old logic and never got updated. Now it lies to readers.\n- **Commented-out code.** `// double oldTotal = subtotal * 1.1;` left behind \"in case we need it\". You don't. Version control already remembers every line you've ever written, so delete the dead code and let `git log` keep the history.\n- **Decorative banners.** `// ============ SECTION ============`. Use blank lines and good method names instead.\n\nComments don't cost anything at runtime, but they cost reader trust. A wrong comment is worse than no comment because readers waste time reconciling code with a description that drifted.\n\n---\n\n# Comment Hygiene\n\nA few habits that keep comments from turning into clutter over time:\n\n- **Keep comments close to the code they describe.** A comment 20 lines above its target is easy to miss when one of them changes.\n- **Update comments when you change code.** Treat them as part of the change, not a side note. A stale comment is a bug.\n- **Prefer a good name over an explanatory comment.** If you're tempted to write `// total including tax`, rename the variable to `totalWithTax` and drop the comment.\n- **Don't apologize in comments.** \"Sorry, this is messy\" doesn't fix anything. Either clean it up or document the actual constraint that forced the mess.\n- **Use Javadoc for anything other developers will call.** Public classes, public methods, public fields. Private helpers can use `//` if they need explanation at all.\n\nA small before-and-after to show those habits at work:\n\n\n```java\npublic class Inventory {\n\n // Before: comment tries to compensate for an unclear name\n public static int adj(int x, int y) {\n // x is current stock, y is units sold\n return x - y; // result is remaining stock\n }\n\n // After: clear names, no comments needed\n public static int remainingStock(int currentStock, int unitsSold) {\n return currentStock - unitsSold;\n }\n\n public static void main(String[] args) {\n System.out.println(remainingStock(20, 7));\n }\n}\n```\n\n\nThe cleaned-up version doesn't need comments because the names carry the information. Save comments for the things names can't express, like *why* a particular threshold or formula was chosen.\n\n---\n\n# Quiz","pageType":"java"}

Comments

Get Premium