Java Glossary : comments

Java definitions: 0-9 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

You are here : home : Java Glossary : C words : comments.

comments

There are three types of comment in Java, /** ... */, /* ... */ and // ... end-of-line. If you write a piece of code with a /** JavaDOC comment, the convention is the comment belongs to the method or declaration following. When you use a // comment on a line containing code, the comment applies to the code to the left.

However, I am not aware of any universally accepted conventions for: /* and // comments on lines by themselves. Do they belong to the line following or preceding? To be consistent, I suggest the following convention: /* belong to the line following, // belong to the line preceding.

It may be advisable to include a blank line prior to a /* comment (and no blank line after that would separate it from the code it describes), or after a run of // comments (and no blank line prior that would separate it from the code it describes) to further clarify your meaning.

I further suggest using /* comments for big-picture forest level overviews and // comments for line-by-line tree level details. Here is an example of comment use:

/* Comment conventions.
A forest type comment,
separated after by a blank line. */

a = b;

/* a comment about the following line. One blank line before, none after. */
c = d;

e = f;
// a detail comment about the preceding line. One blank line after, none before.

g = h; // a detail comment about this line

home	Canadian Mind Products
	mindprod.com IP:[24.87.56.253]
	Your IP:[80.134.30.163]
	You are visitor number 799.
	Please send errors, omissions and suggestions
	to improve this page to Roedy Green.
	You can get a fresh copy of this page from:	or possibly from your local J: drive mirror:
	http://mindprod.com/jgloss/comments.html	J:\mindprod\jgloss\comments.html