Now that we have explored the various ways we can comment on code and commenting styles, let's copy hello1.c to hello2.c and add appropriate comments.
You can either copy hello1.c to hello2.c with your command interpreter or, in your editor, open hello1.c and immediately save it as hello2.c. Regardless of how you do this, you should have both hello1.c and hello2.c in your Chapter1_HelloWorld directory.
In your editor, modify hello2.c so that it looks as follows:
/*
* hello2.c
* My first C program with comments.
* by <your name>
* created yyyy/mm/dd
*/
#include <stdio.h>
int main()
{
printf( "Hello, world!\n" );
return 0;
}
/* eof */
Note how the * at the beginning of each line providing a comment makes it clear that there are several lines of comments in a group; the group begins with /* and eventually ends with */. Compile, run, and verify this program. Be certain you haven't introduced an accidental character here or there, which is always possible and should always be verified.
This is now a complete program. We know from the evidence from hello1.c that the program is correct– it displays our intended message in the way we desire. The first six lines of comments provide minimal information about the program's author and the date it was written. This program's heading information may be simple or it may be more comprehensive. For now, we will keep such heading information simple.
The program itself is so simple that anyone who understands C would know that a simple message is printed. No further commenting is needed here.
Finally, we mark the end of the file with a comment; the only benefit to such a marking is when there are multiple editor windows open and/or programs get very long. This simple demarcation lets humans know we're at the EOF. This final EOF indicator is entirely optional and becomes more of a stylistic preference than a practice with rigorous rationale.
I have found that in every programming language I have used, my commenting style has adapted to the clarity or obtuseness of the given language. When I programmed in assembler language at university or later in an early version of Fortran 4, I commented on almost every line. But for C++ or Objective-C, I found I comment only sparsely or in globs– large sections of comments that explain a concept or programming solution.
Furthermore, even within a given language, when the problem being solved is unusual or I am using a novel approach to its solution, more comments are in order.
In the remainder of this book, depending on the code sample, we'll explore various useful commenting practices that are effective, even when the code is subject to change.
