April 2000

Source Code Typesetting Practices

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 ]

The Essential Example

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.

The Beginning of a C Source File

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 Fubu Bar

    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: mui <fu@bar.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.

Important Notes

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.

Function Boxes

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.

In Lines and Small Block Explanations

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.

Section Headers

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()
{
    ...
    ...

Attention Getter Blocks for Whole Sections

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.

Danger Will Robinson

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 Much is Enough?

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):

  • Always have a short description for functions.
  • If appropriate break up the program with section headers.
  • Try to describe variables unless they are pretty apparent.
  • Always close nested iterations with end comments.
  • Always put end comments after functions.

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.

Make a Style Guide

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.

These Are Suggestions, Form Your Own Practice

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.

Footnotes

  1. From Practical C Programming 3rd Edition Copyright (c) 1997, 1993, 1991 by Steve Qualline.
  2. The use of the name YAKKO is completely and utterly arbritrary, no persons named YAKKO were harmed in the making of this column.