Comments

Code is written once and read many times. You’ll come back to something you wrote last week and forget what you were thinking. Someone else will read your code and need to understand it without asking you. Comments let you leave notes directly in the code, so the reasoning is there when anyone needs it.

More importantly, the habit of commenting is worth building now, before your programs get complicated. It’s much harder to retrofit the discipline later.

Single-line comments

The most common kind starts with //. Everything from those two slashes to the end of the line is ignored when the program runs.

You can also put a comment at the end of a line:

Both work. The above-the-line style suits longer notes; the end-of-line style suits brief ones.

Comment the why, not the what

This is the most important habit to build. The code already shows what it does. What it can’t show is why.

Here’s a comment that adds nothing:

Anyone can see it prints a welcome message. The comment just repeats the code in English.

Here’s a comment that earns its place:

That tells you something the code itself doesn’t. That’s the standard to aim for.

Multi-line comments

When a note needs more than one line, wrap it between /* and */. Everything between those markers is ignored, across as many lines as you like.

The leading asterisks on each line are convention, not a requirement. Most codebases use them because they make the block easy to spot at a glance.

Javadoc comments

There’s a third kind that starts with /** (two asterisks). These are called Javadoc comments.

You don’t need to write these yet. They’re used to document code in a way that tools can read and display automatically. You’ll see them constantly when reading Java’s own documentation. For now, just recognize the format: double asterisk after the slash means Javadoc.

Commenting out code

You can also use a comment to disable a line temporarily without deleting it:

The middle line won’t run. This is handy when you’re testing and want to silence something temporarily.

That said, don’t leave commented-out code sitting in a file permanently. It clutters things up and confuses anyone reading later. If you’re not going to use it, delete it.

What good commenting looks like in practice

Here’s a small program with comments applied the right way:

Each comment explains something the code alone doesn’t tell you. That’s the goal.