April 2000
Did you ever notice that when you read a programming book, guide or tutorial, the commenting is thorough and helpful? Then shortly thereafter you cracked open some source code and sort of thought - okay, there is a difference between the real world and schooling? Well that is not exactly news, just about every profession is like that one way or another, however, that does not mean it is without hope. A look at source code typesetting, or as Steve Qualline puts it, "Poor Man's Typesetting." [ 1 ]
There is nothing I love more than someone saying "You should do this that way" and then leaving without making a single suggestion. With that in mind, I will proceed by section through a single C program file which, in effect, does nothing but a bunch of prints, but is easy as an example.
NOTE: For sake of keeping this page readable I made long lines well under 79 to 80 characters. Normally I prefer to run long ASCII bars or borders right up to 78 characters.
At the beginning of most program and header files, writers like to keep information about the file's function, their names and license information. Now here is the odd ball thing about these sections, a lot of software writers make them boxed in and sometimes a bit eccentric, for example here is a somewhat garish one: [ 2 ]
/******************************************************************** * fooprint.c: fooprint program file * ******************************************************************** * * * This source code is licensed under YAKKO * * * * YAKKO will hunt you down like the dog you are if you copy this * * redistribute it or even look at it the wrong way. * * YAKKO is watching you. * ******************************************************************** * Author: Yakko B. Yakkohanson * * Date: April 1st, 2010 * ********************************************************************/
Of course if left completely out of control that box could get seriously ugly. Since it is at the beginning of a file and not likely to get confused with say actual source code, why not opt for something a little lighter on the eyes like:
/******************************************************************** * fooprint.c: fooprint program file * * * * This source code is licensed under YAKKO * * YAKKO will hunt you down like the dog you are if you copy this * * redistribute it or even look at it the wrong way. * * YAKKO is watching you. * * * * Author: Yakko B. Yakkohanson * * Date: April 1st, 2010 * ********************************************************************/
Or as I like, the ultra light version:
/*
fooprint.c: fooprint program file
This source code is licensed under YAKKO
YAKKO will hunt you down like the dog you are if you copy this
redistribute it or even look at it the wrong way.
YAKKO is watching you.
Author: Yakko B. Yakkohanson
Date: April 1st, 2010
*/
One could argue that the last example is too light and does not safely indicate a comment. Well with a large license statement it looks like a very well formed block. Take the GNU GPL for example:
/*
foooprint.c: fooprint program file
Copyright (C) 2000 Jason R. Fink
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
Contact Information:
E-mail: jrf <jay.fink@gmail.com>
*/
As you can see, in a large block of text, block commenting is especially useful, however, I prefer only to use it at the beginning of a C source file.
If there are any important notes I want to include in the source code that apply to the whole file or program (or both) I usually like to use a style that sort of sets them apart. I prefer this for notes because it looks similar to logfile entries:
/*------------------------------------------------
NOTE: I stole this from that guy YAKKO
he is not very nice.
------------------------------------------------*/
This style is also favored for boxes before functions as well.
By far the most popular C function box style is:
/*************************************************** * print_foo_one: Prints the first part of foo. * * * * Parameters: None * ***************************************************/
Again I go for a lighter version but only slightly so:
/*************************************************** * print_foo_one * Prints the first part of foo ***************************************************/
These are not all that different, my little tiff is that I do not like having to close up the right end of the boxes due to the dynamic nature of their contents.
Whenever I have a simple short little comment to drop (like say a variable's true purpose) I like to use either an inline right above it or (more appropriately) a single comment on the same line off to the right, following are two examples:
print_foo_one()
{
/* First Counter */
unsigned int count_one;
unsigned int count_two; /* Second Counter */
...
For variables, I prefer the second method, it looks cleaner:
print_foo_one()
{
unsigned int count_one; /* First Counter */
unsigned int count_two; /* Second Counter */
...
There are also instances within a function where you might want to explain some code but it takes a little more detail. I always try to put this information in a single line above the code, but, if I do not have the room I simply write a short block. Following is an example of the first style:
...
/* This checks the First Counter */
if(count_one > 10) {
printf("De foocounter is higher than 10!\n");
} else {
printf("De foocounter is less than 10.\n");
} /* end if count_one */
...
It could be too short, for a little more I might try:
...
/*
* The following checks the condition
* of the First Counter and lets the user
* know if it is over the high water mark
* also known as 'foomark'
*/
if(count_one > foomark) {
printf("De foocounter is higher than 10!\n");
} else {
printf("De foocounter is less than 11.\n");
} /* end if count_one */
...
Also take note of the end if comment, especially helpful in nested loops, ifs or any combination thereof.
In programs that are only one source file or have a great deal of functions even in multiple files I like to break them up into "virtual sections" to help show a degree of modularity. Sometimes it becomes difficult to completely make a program modular, so using a device as a sort of section header helps out. In the example below I show three headers, one for small utility functions that are reused all over the place, functions and the main function:
/* >>>>>> Utility Functions <<<<<<<<<<<<<<<<<<<<<<<< */
...
...
...
/* >>>>>> Functions <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< */
...
...
...
/* >>>>>> Main <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< */
int main()
{
...
...
Sometimes a whole function or section of code may need some general explaining that goes beyond the reasonable size of say the function box or a block description in the previous section. In this instance I like to use a sort of weird one that grabs the attention of the reader but not so much that it is distracting:
/* * YAKKO Really messed up this whole section * ^^^^^ ^^^^^^ ^^^^^^^^^ ^^^^^^^^^^ ^^^^^^^ * * He tried to use recursion but ended up * segfaulting the program. Not only is he * not nice but he is an idiot. */
This particular type of comment is very flexible, one could easily substitute the carets with lines, dashes or underscores.
Last but not least, something I never like to see in a program (but have put into Betas myself) is a danger sign. There are many variants on it with one general theme, Get the Readers ATTENTION! AT ALL COSTS.
I think you get the idea. Anyway, here is a stock example:
/*************************************************** *************************************************** ****************** WARNING! *********************** ******* This program will self destruct *********** *************************************************** ***************************************************/
As per the norm I like to go with something a little lighter:
/*************************************************** *************************************************** ****** WARNING!!! ****** This program will self destruct *************************************************** ***************************************************/
I prefer that style because it still will get the attention of the reader and as I mentioned before, I am lazy and do not like closing up boxes.
How many comments should be in source code? When is there too much? Too little? I like to operate on some general guidelines (none of which I have written down):
That seems pretty easy to me. I do try to have as brief a message as possible, but many times I leave comments (especially inline) as a reminder to myself or as a question for those who might be reading my code.
People usually cringe at the thought of even more documentation, but, it helps more for the writer than anyone else. I have one in a single tiny file I leave laying around in case I do not have an example handy. Just one plain ASCII file will suffice, my current C one is available for anyone who is curious about it.
By no means should anyone use my style, feel free to make your own. Check out some coding standards out there and see if they fit the bill even better.
(based on last 2 months log reports)
