Pro Java 9 Games Development Leveraging the JavaFX APIs

Chapter 5 ■ a Java primer: introduCtion to Java ConCepts and prinCiples

and the reverse of that, using an asterisk and then a single forward slash, to end the multi-line comment
(this kind of comment is also called a block comment). These are the two ways that you will generally add
short (single-line) or long (multiline) comments to your pro Java games.
It is important to note that you cannot “nest” multiline comments. Simply use a larger multiline
comment!
In case you are wondering, this InvinciBagel project was the i2D arcade game that I taught readers
how to create in the Beginning Java 8 Games Development book I wrote for Apress covering i2D game
development using Java 8 and JavaFX 8. All of the principles in that book apply to Pro Java 9 Games
Development, so I’m using that code here.
I usually line up my single-line comments to look fairly orderly. The Java convention for block
commenting is to line up your asterisks, with an asterisk in your beginning comment delimiter and one in
your ending comment delimiter. This is shown in Figure 5-1 at the top of the InvinciBagel.java code editor
tab in NetBeans.
There is a third type of comment called a Javadoc comment, which you’ll not be using in your pro Java
game development in this book, as the code is intended to be used to create your game and not distributed
to the public. If you’re going to write a Java game engine for use by others to create games, that is the point
in time when you would use a Javadoc comment to add documentation to your pro Java game engine. The
JDK has a Javadoc tool that is used to process the Javadoc comments and add them into the NetBeans 9 IDE.
A Javadoc comment is similar to a multiline comment, but instead it uses two asterisk characters to create
your opening Javadoc comment delimiter, as I have done here:

/* This is an example of the Java Documentation (Javadoc) type of Java code commenting
This is a type of comment that will automatically generate your Java documentation!
/

If you want to insert a comment right in the middle of your Java statement or programming structure,
which you should never do as a professional Java games developer, you would use the multiline comment
format, like this:

import / This line of code imports the Stage class / javafx.stage.Stage;

This will not generate any errors but could confuse the readers of your code, so don’t comment the
code in this way. The following way of commenting this, using a single-line comment format, will, however,
generate errors:

import // This line of code will not successfully import the Stage class javafx.stage.Stage;

This is because the compiler will see only the word import, as this single-line comment parses to the
end of the line, whereas the multiline comment is specifically ended using the block comment delimiter
sequence (asterisk and forward slash). For this reason, a Java compiler will throw an error for this second
improperly commented code, essentially asking “import what?” Since you cannot import nothing, you must
import a Java class from a Java package.