More code comments

As you become more advanced at writing Java programs, the solutions you use to create your programs will become longer and more complicated. Furthermore, as we will see in later chapters, Java was designed to manage complexity by having us divide up our code into separate classes, very often across multiple files.

Code comments are a part of the Java program that do not have any function in the program itself. The compiler ignores them. They serve to help the programmer document, explain, and clarify their code to make it more understandable to themselves at a later date, or to other programmers who might need to use or modify it.

We have already seen a single-line comment:

// this is a comment explaining what is going on

The previous comment begins with the two forward slash characters //. The comment ends at the end of the line. So, anything on that line is for humans only, whereas anything on the next line (unless it's another comment) needs to be syntactically correct Java code:

// I can write anything I like here
but this line will cause an error

We can use multiple single-line comments:

// Below is an important note
// I am an important note
// We can have as many single line comments like this as we like

Single-line comments are also useful if we want to temporarily disable a line of code. We can put // in front of the code and it will not be included in the program. Remember this code, which tells Android to load our layout?

// setContentView(R.layout.activity_main);

In the previous situation, the layout will not be loaded and the app will have a blank screen when run, as the entire line of code is ignored by the compiler.

There is another type of comment in Java known as the multi-line comment. The multi-line comment is useful for longer comments that span across multiple lines, and also for adding things such as copyright information at the top of a code file. Similar to the single-line comment, a multi-line comment can be used to temporarily disable code, in this case across multiple lines.

Everything in between the leading /* and the ending */ is ignored by the compiler. Here are some examples:

/*
  You can tell I am good at this because my
  code has so many helpful comments in it.
*/

There is no limit to the number of lines in a multi-line comment. Which type of comment is best to use will depend upon the situation. In this book, I will always explain every line of code explicitly in the text but you will often find liberally sprinkled comments within the code itself that add further explanation, insight, or context. So, it's always a good idea to read all the code thoroughly too:

/*
  The winning lottery numbers for next Saturday are
  9,7,12,34,29,22
  But you still want to make Android apps?
*/

Tip

All the best Java programmers liberally sprinkle their code with comments!