Title: Mostly Comments

In his article 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 have 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 are 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 would comment out the #include. In fact you would probably have already done that so you could run the regression tests. On balance I would not create a separate comment file.

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 is 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 ACCU, 1997-2000. All rights reserved.
// Full copyright, disclaimer and maintenance-
// history at end of file
#include <list>
#include "accu/graphic.hpp"
#include "accu/cloner.hpp"

namespace accu {
  class compound : 
    public graphic, public cloner<compound>   {
  public:
      ...
  private:
    std::list<cloning_ptr<graphic> > graphics;
    };
}
// Example of use goes here

// Permission to use, copy, modify, distribute 
// this software and its documentation for any
// purpose is hereby granted without fee,
// provided that the above copyright notice
// appear in all copies,that both that copyright
// notice and this permission notice appear in
// supporting documentation, and no charge may
// be made for the software and its
// documentation except to cover cost of
// distribution.

// ACCU makes no representations about the
// suitability of this software for any purpose.
// It is provided "as is" without express or
// implied warranty. Blah blah blah

// Maintenance history goes here and usually
// rambles on for ages and ages

I am not suggesting that you need to start the code immediately. I think it is 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 do not want to scare them too much. I particularly like comment on the second line:

// Full copyright, disclaimer and maintenance-
// history 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 do not need to know. And there is more information supplied elsewhere if we want to look. Incidentally, I have 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?

The idea of putting the code first and the comments last is very reminiscent of the need-to-know ordering in a class definition^[3]: 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 realised 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 would 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 strongly prefer this ordering.

One more comment on comments.

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

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

I cannot 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 are 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 is all for now

P.S. Now if only my editor would allow me to format the code (with its included code-comments) in a monospace font and the post-code gumpf-comments in a nice proportional font.