This time we'll talk about comments in Java. Comments are worth knowing because they explain the code you write.
Java has several kinds of comments:
- Single line comments
- Multiline comments
- Doc comments
Let's go deeper.
About Comments in the Java Language
A comment, or comments, is a block of code the computer won't read and won't execute. Even so, comments serve an important purpose.
Comments help a programmer understand the intent of code that was already written.
When you write a program, you know exactly what the code you typed means. But what happens if that code sits untouched for days, or even years?
Programmers are human too, and humans forget things, so chances are you'll forget what you wrote. Especially if the code is messy and the names are unclear. Ugh... that's rough ๐.
This is where writing comments matters. With a comment, you can describe the code in human language, which is certainly more human than computer language.
Beyond that, a comment also works as a debugging tool. You can tell the computer to ignore a line of code without deleting it.
Writing Comments in the Java Language
You can place a comment anywhere you like. You can write anything inside one too. It doesn't have to be program code. Writing a poem in a comment is fine as well.
To write a comment, Java has 3 different syntaxes:
Single Line Comments
As the name suggests, this comment can only be written on a single line.
A single line comment starts with the // sign. Example:
// This is a single line comment
// This code is outside the class block
public class HelloWorld {
// This code is inside the HelloWorld class block
public static void main(String args[]) {
// This code is inside the main function block
System.out.println("Hello World!"); // This line prints "Hello World"
}
}
If that code runs, nothing changes from before. That's because the computer doesn't execute comments.
Multiline Comments (Multi Line Comments)
With multi line comments you can write one or several lines of comment inside a single comment block.
The rule is to open with /* and close with */. Example:
/* This is a multiline comment
This code is outside the class block */
public class HelloWorld {
/*
This code is inside the HelloWorld class block
this is a new comment line
still inside the same comment block
*/
public static void main(String args[]) {
/*
This main function is called first
by the computer. The code below aims to
print "Hello World" on the console screen
*/
System.out.println("Hello World!");
/* a multi line comment also works for a single line comment */
}
}
Doc Comments
Last come doc comments.
These have a special purpose, generating documentation for the code you write. Java has a tool called JavaDoc that builds documentation from comments.
Doc comments use syntax like multi line comments, except the opener is /** and every comment line must start with a *. Example:
/**
* Main class of the "Hello World" program
* @author Inva
*/
public class HelloWorld {
/**
* Main function that the computer calls
* Prints <code>Hello World<code> on the console screen
* @params no parameters are used
* @return returns nothing
*/
public static void main(String args[]) {
System.out.println("Hello World!");
}
}
Writing this kind of comment isn't free-form, JavaDoc has its own specification. For more, see the JavaDoc guide page.
Because its purpose is specific, we won't use doc comments in this Learn Java series.
Next Up
Comments may look useless to the computer, but they help a programmer read the program. So don't hesitate to write comments.
In later pieces you'll often see comments sitting between lines of code, so don't get confused. They're only explanations, and leaving them out is fine too.
Next we'll talk about the output system in Java.
Happy coding ๐