Publications
of Jon Jagger
jon@jaggersoft.com
Appeared in CVu 12.3, May 2000

Mostly Comments

Code file and comment file?

In one of his recent articles Francis wrote,

“I personally hate comment that is invasive of the code.”
In his next paragraph he added,
“While there is a good case to be made for recording the development and maintenance history of the source code somewhere I question whether it is correct to place that in the same file.”
Francis is clearly suggesting that the information describing the development and maintenance history of the source code should go into a different file. I have a lot of sympathy with this view. Often when you read a source file the first thing you encounter is a mass of comments: copyright-notices, standard-disclaimers and maintenance-histories to name but three. It gets in the way. It is invasive. No question. But should you split these comments off into a separate comment file? As always, there are conflicting forces. A separate comment file would certainly make the code file more focused. And it would also make the code file smaller. In some cases a lot smaller. That could make compilation faster. That might be an issue. On the other hand a separate comment file might be just too easy to mislay (I've heard of source files being lost and developers being left with just the object files!) Now you could place a #directive in the source file that included the comment file. That might help, but only a little. Consider: You're up against a rapidly approaching deadline, you fix the last bug, the regression tests all pass, but aaargh, the comment file is missing. What would you do? Be honest. You'd comment out the #include. In fact you'd probably have already done that so you could run the regression tests. On balance I would not create a separate comment file.

Not me. I just want to code and go

The most important thing in a source file is the source code. The source code is the reason the source file exists. If there were no source code there would be no comments (and if there are no comments there's no point arguing if they should live in their own file.) There is a priority. Recognition of this priority suggests a solution less radical than factoring out the comments into a separate file; simply place all the "gumpf" (to use a technical term) at the end of the source file. After the code. Order the file contents based on their priority.

// Copyright {JSL}, 2000-2002. 
// All rights reserved.
// Maintenance-history, disclaimer 
// and full copyright at end of file

#include ...

namespace jsl
{
    class loud_bool
    {
    public:
        ...
    private:
        ...
    };
}

// Examples of use go here
// ...
// Full maintenance history goes here
// ...
// Full disclaimer goes here
// ...
// Full copyright goes here
// ...

Forward comment

I'm not suggesting that you need to start the code immediately. I think it's fine to start with a few comments. But only a few. In fact a few is probably a good idea. After all, most programmers are used to seeing reams and reams of comments at the top of source files. You don't want to startle them too much. I particularly like comment:

// Full copyright ... at end of file

This is very reminiscent of a forward declaration.

struct body;

It tells us all we need to know, and nothing we don't need to know. And there is more information supplied elsewhere if we want to look. Incidentally, I've never been quite sure why a forward declaration is called a forward declaration. It kind of suggests there is such a thing as a backward declaration, which there isn't. Why isn't it just called a declaration?

Need to know ordering

The idea of putting the code first and the comments last is very reminiscent of the need-to-know ordering in a class definition - public before protected before private. Code before comments is just another example.

I was thinking about this idea of a need-to-know ordering as I mentally prepared this article. As I did so I realized a couple of things. The first is that it does not apply just to access specifiers. If I had a class that publicly derived from one class and privately derived from another class, I'd place the public derivation first. The second is that there can be a need to know ordering within declarations with the same access. For example, consider this fragment:

namespace accu
{
    class Francis
    {
        ...
    private: // data
        ...
    private: // prevention

        Francis(const Francis &);
        Francis & operator=(const Francis &);
    };
}

This fragment implements the Francis class. Now Francis has strong identity (no argument there). You cannot copy Francis (be grateful for small mercies), and we have declared in code that you cannot copy a Francis, since the copy constructor and copy assignment operator are private. No problem. But compare the fragment to:

namespace accu
{
    class Francis
    {
        ...
    private: // prevention

        Francis(const Francis &);
        Francis & operator=(const Francis &);

    private: // data
        ...
    };
}

The only difference is the ordering of the two sections that are both private. In this fragment the prevention is before the data. I prefer this ordering.

Comment noise

One more comment on comments.

/******************************************** 
 * How do you make toast?                     
 ********************************************/

/*------------------------------------------*/
/* You burn bread and scrape the burn off!    
/*------------------------------------------*/

I can't stand all the noise around comments like these. Look closely. The comments are the words. Just the words. All the rest, all the stars and all the dashes contribute nothing. They're just noise that the eye and mind has to discard. Get rid of them.

// How do you write software?

// You write code with bugs in it 
// and then scrape the bugs off!

That's all for now.
Cheers
Jon Jagger
jon@jaggersoft.com