Java Comments




Java Comments
-------------

In Java, there are three types of comment available:


1. Single line comments
-----------------------

Any lines in a Java program
that start with the // symbols are known as comments.
Comments are ignored when the program runs,
but they're useful when we read a program, 
because they supply information about the program.

Comments are always used at the top of a program
to supply information about the purpose of a program,
its file name (e.g. prog_01_01.java), the name of the programmer,
the date last updated, the current status (completed, incomplete) 
and any other pertinent information.


Comments are also used in the body of a program 
to explain parts of the program
which may be hard for the reader to understand.

Comments may be added to the end of any statement in a Java program
by typing the // symbols first.

Example programs in this course demonstrate the correct use of comments.




2. Multi-line comments
----------------------

As explained above, if you want to convert a line into a comment,
simply type // at the start of the line.

If you have several lines to change into comments,
you can place a // at the start of each line.

To save on having to type a // at the start of multiple lines,
there's another way to convert several lines of
a program file into comments, ...

Sometimes we need comments which span several lines in a program.



As long as the block of statements starts with the characters
/*
and ends with the characters
*/
those lines will be ignored by the Java compiler/interpreter 
(i.e. will NOT be executed).



Multi-line comments are useful when you want to "comment out" a block of statements.
"Commenting out" means to convert the statements into a comment
so that they will not be executed.
This is an alternative to deleting the statements.




3. Javadoc comments
-------------------

Javadoc comments are used to document the new classes you create as a programmer 
i.e. provide information about the class for users of the class to read.

Until you start to create new Java classes, just use the first two methods shown above
to document your Java programs.



If you've created any new classes yourselves, read on...

javadoc.exe is a program which will automatically generate an html document
which includes information about your class - useful information for users of your class.

For an example of a class and its javadoc html page,
visit here.



At the top of your source code,
provide a comment block which starts with the characters
/**
and ends with the characters
*/

Those lines will be ignored on program execution, 
but will be extracted into a web page (html file) 
of useful documentation for that program class
after using the program javadoc.exe.
javadoc.exe is included in your Java installation.

Click here 
for an example of the use of javadoc 

For an example of a class and its javadoc html page,
visit here.







Documentation
-------------

In the real world, programmers document each program that they write.
This is because programmers work in teams and have to work on
each other's programs. In its simplest form, documentation of a program
includes the file name, programmer's name and date last updated in comments
at the top of the code.



As students of a programming course, you're expected
to supply an appropriate set of comments
for all of your lab and homework programming assignments.


Valid XHTML 1.0!

Valid CSS!

Anne Dawson © 1995-2016 All Rights Reserved.