Chapter 3
Use Comments Wisely

One of us (Jörg) recently bought a new TV—a smart TV with all kinds of apps, streaming services, and different ways to program a time-based video recording. Turns out, this smart TV is only as smart as the person using it, and learning how to get all the new features to work isn’t all that straightforward. You’d have better luck teaching yourself a few new swear words than finding the folder where the TV stores a new recording. And why doesn’t it warn you that it’s going to stop recording if you hit the Power button?

That’s when most people pick up the user manual. The manual is the documentation—it’s there to help you with clarification. It should tell you things like where you can find your recordings and how to record something without watching it at the same time. But with this smart TV, picking up the manual only caused more frustration. In the section titled “The Record Button,” all it says is, “Starts the recording.” Anyone could figure that much out just by looking at the red Record button! And what happens if you hit the Power button during recording? It doesn’t say.

User manuals are meant to tell you how something works. Same thing with comments in your code: their purpose is to tell you how a piece of code works. Unfortunately, code comments are often like our smart TV’s manual—not helpful. For example, maybe they just repeat what’s already in the code. Or worse—they’ll tell a different story than the actual code.

In this chapter, you’re going to learn how to make your comments more helpful. In the pages that follow, we’ll help you sharpen your senses for when to use comments and when to avoid them. We’ll show you types of comments that are simply superfluous, tell you what to do with code that’s been commented out, and introduce you to a few tricks you can use to replace a comment with code. Finally, we’ll explore the commenting conventions in Java so you’ll be able to write high-quality JavaDoc comments. Let’s get started.