Comments
It is often the case that you want to include comments within your Java code.
Comments are little bits of documentation embedded in the actual code that are invisible to the Java compiler but which can be read by a person reviewing your code.
Comments help to document what it is that your code does and how someone should understand the design if they want to modify something.
Comments are essential if someone else is going to work with you or take from where you've left off.
Comments also help you think about inefficiencies in your own code.
Trying to explain how a bit of code works to someone new to it is always one of the best ways to catch your own mistakes.
Often the act of documenting helps you realize that you've done something in an awkward way.
If your code is clean and makes sense, it should be easy to document.
If your code is hard to document, perhaps you'd better think about rewriting!
Finally, it is important to learn commenting style over time.
For example, there is little reason to say:
i++; // increment i by one!
Spend your time commenting how routines work in the large rather than each individual line.
Of course, if there are some gnarly single lines of code in your application, feel free to document them.
Use your best judgement and find your own voice!
There are actually several ways to denote comments in Java
For single line comments, you can use the "//" notation.
For example, consider the following code:
// Initialize variables...
int age = 28; // Declare and initialize age
Note that single line comments can be defined on the same line as your code or on their own line
To specify multiline comments, however, you will use the "/*" and "*/" combination such as in the following example:
/*
This is a sample class which is used to demonstrate
the use of multi-line comments. It was written by
Selena Sol for the Web Programming Tutorial
*/
// Define an Example class with a single
// main() method which will print out
// "Hello Cyberspace!" to standard output.
public class Example
{
public static void main(String[] args)
{
System.out.println("Hello Cyberspace!");
}
}
As you can see, if you use the "//" notation and your comment spans multiple lines, you must begin each new line with a "//" combination.
Finally, if you are writing comments that should be included as part of a javadoc document, you should use the "/**" "*/" combination such as in the following example:
/*
This is a sample class which is used to demonstrate
the use of multi-line comments. it was written by
Selena Sol for the Web Programming Tutorial. This comment
does not appear in the java documentation
*/
/**
Define an Example class with a single
main() method which will print out
"Hello Cyberspace!" to standard output.
This comment appears in the javadoc.
*/
public class Example
{
public static void main(String[] args)
{
System.out.println("Hello Cyberspace!");
}
}
NEXT
Selena Sol contributes to the JavaBoutique's Introduction to Java. Selena curently works for Barclays Capital in London, one of the leading global investment banks in Europe and has worked as a software developer for the National Center for Human Genome research, Microline Software, Neuron Data, and Electric Eye in Singapore. Selena is perhaps best-known for creating the Public Domain Web Script Archive (Extropia) and writing several books on Web Programming (Perl, CGI, Java).
Email: selena@extropia.com
New on the Java Boutique:
New Review:
Time Management Made Easy with the Quartz Enterprise Job Scheduler
Why not just use the Java timer API? This open source scheduling
API boasts simplicity, ease-of-integration, a well-rounded feature
set, and it's free!
New Applet:
Reverse Complement
Reverse Complement is a simple applet that converts DNA or RNA
sequences into three useful formats.
Elsewhere on internet.com:
WebDeveloper Java
Lots of Java information on webdeveloper.com
WDVL Java
Thorough Java resource at the Web Developer's Virtual Library.
ScriptSearch Java
Hundreds of free Java code files to download.
jGuru: Your View of the Java Universe
Customizable portal with online training, FAQs, regular news updates, and tutorials.
| 
