Comments

Now is a good time to look at an essential part of coding that gives no instructions at all. In fact, the JVM explicitly does nothing with these lines. Just as you might see notes in the margin of a novel or textbook (explaining why something is important, connecting something you just read to something else, reminding yourself to come back later, etc.), you can, and should, do the same in code.

Java calls these little notes to yourself, without any bearing on the execution of the program, “comments.” The process of writing them is called “commenting” or “documenting” and, even early on, is just as essential to getting code done right as solving the problem correctly or solving the correct problem.

Every language has some delimiter that it looks for in lines of code, where, if it finds it, it ignores whatever is inside as a comment, not an instruction. In some languages, it’s ; or ;; (but recall that in Java, ; ends a statement which is code); in others, it’s # or ##. Java has two comment styles, based on different lengths: for short comments that take up just one line, and for longer multi-line comments. You can, if you wish, write a multi-line comment in that style, or with a bunch of single-liners.

Java’s single-line comments are indicated by //-- two forward slashes. Anything else in the line after two forward slashes will be ignored and treated as a comment, not an instruction. Multiline comments start with /* and end with */. Anything inside there is considered the comment.  

As you progress along your software development journey, you’ll become more and more aware of what needs comments and how detailed they should be. Just remember—you’re leaving notes to your future self (or someone else you may not know) about what the code does so that they can keep using, changing, or fixing it in the future.

Here, for example, is a well-written, functional Calculator class, missing any comments:

public class Calculator {

    public int add(int a, int b) {

        return a + b;

    }

    public int subtract(int a, int b) {

        return a - b;

    }

}

And now here is the same class, but with descriptive comments:

public class Calculator {

    /* This method adds two integers */

    public int add(int a, int b) {

        // Return the sum of a and b

        return a + b;

    }

 

    // This method subtracts the second integer from the first

    public int subtract(int a, int b) {

        return a - b; // Return the difference

    }

}

These examples are very simple, but even from something at this level, you can see how comments make it easier to know what to expect before reading a method in depth.

Generally, IDEs—at least IntelliJ—color-code things based on what they are. Reserved words like “public” or “static” or “int” are one color; method names like toString() are another color; properties, like “breed” in Dog.breed are the same color as method names; String literals, like “I like pizza” are a different color, etc. This helps someone just skimming the code know what things are, even at skimming speed. Most text, as in instructions, is just plain black. But comments are different. Most of the time, they appear as gray, but if you start your comments with certain words like “TODO” (not necessarily all uppercase) or “fixme” (not necessarily all lowercase), then the IDE will help you by color-coding those comments differently than regular ones, or anything else (usually in bright blue), to help draw your attention to the fact that you haven’t finished something, or that you’ve found a bug somewhere and need to fix it.

It takes time to learn how to write good comments, so don’t worry if you think you’re writing comments that are obvious—like, above a line “int x = 0;” writing “// this is an integer called x and its value is 0”—in the beginning. Those comments are an important stepping stone toward really good ones. As an exercise, go back through all the code you’ve written so far and write some comments.

And remember that comments are changes, so re-run your programs to test them and make sure they still work, since you might have accidentally commented out something you didn’t intend to!