Comments

Describes purpose and syntax of comments

Comments are text notes which can be read by humans but are ignored by the compiler. Including comments in your code helps make it easier for you and others to read it. Comments are especially useful to record the intent of a particular piece of code, since it may not be clear to others or, after a period of time, to the original programmer. That said, code readability is not achieved exclusively by including comments. It is also enhanced by adhering to coding conventions and using explicit variable and object names.

Under PBL, comments can be single line or multi-line, and are delimited either with standard C++/Java syntax in the Java and PBL Styles, or with Visual Basic syntax in the Visual Basic style, as described below.

Tip: Always remember that when you write comments, you should explain the why and not the how. The how can be read from the code itself.

PBL and Java Style Comments

Single line comments are denoted with a double forward slash (//):

//This is a single line comment.

Multi-line comments are enclosed between a forward slash and an asterisk (/*) and an asterisk and a forward slash (*/):

/* This is a multi-line comment. It can span multiple lines
of code and can be as long as you want it to be.
You do not have to worry about line breaks, although
you may add them if you want to. */

Visual Basic Style Comments

Visual Basic style uses a single apostrophe (') for single line comments:

' This is a comment in the Visual Basic style.