Creating a Java Application and Applet - Java Programming: Comprehensive Concepts and Techniques - page 61

Coding the Program
As you have learned, the implementation phase of the program development
cycle involves writing the code that translates the design into a program. During
program design, a flowchart was used to outline the logic of the program code in
the Welcome to My Day application (Figure 2-4a on page 51). As outlined in that
flowchart, the task to be performed is to display a welcome message, the user's
name, and the system date on the screen. Implementing the code to perform the
task, instructing the computer to save that set of instructions, and then learning
how to execute those instructions on any computer platform or the Web is a
stepping stone to creating larger, more intricate, and more useful programs.
Coding Comments as Documentation
The process of writing code, or coding, includes adding internal
documentation in the form of comments , which are notes within the code
that explain the purpose of the code. These comments describe the purpose
of the program, the name of the programmer, the date, and other important
information for the programmer and other users.
When writing code, it is a good programming practice to include comments
at the beginning of a program and at the start of every major section of a pro-
gram. When it is necessary for a programmer to review program source code,
these comments provide an immediate description of what the program is going
to do. Comments also help the programmer think clearly about the purpose of
the upcoming code.
Comments are not executed when the program runs. Comment lines display
in the coding window and on printouts of the source code, but they do not cause
the computer to perform any task.
In Java, comments can take several different forms. A block comment
begins with a forward slash followed by an asterisk (/*) and ends with the
symbols reversed, an asterisk followed by a forward slash (*/). Block comments
can span as many lines as necessary within the beginning and ending marks.
Comment Placement
Comments provide important program information and remind
you and other programmers of the purpose of code. Use com-
ments in the following three ways:
1. Place a comment that identifies the file and its purpose at
the top of every class or file that contains code. This type of
comment typically is called a comment header .
2. Place a comment at the beginning of code for each event and
method.
3. Place comments near portions of code that need clarification or
serve an important purpose.
Typically, each line within a block comment is indented for ease in reading.
Block comments can be placed before or after any line of code. All of the lines in
the block, however, must stay together in a block; they cannot be interrupted or