File Headers

From SelfDocumentingCode...

Place a short description of the module at the top of each file.

For example, I always write a header in the form of:

 // TimerThread.h -- A thread that calls a callback based on a system
 // -------------    timer.
 // September 22, 1999 -- SS
if it belongs to someone else or

 // TimerThread.h -- A thread that calls a callback based on a system
 // -------------    timer.
 // September 22, 1999 -- Copyright Sunir Shah. All rights reserved.
 //                       (
if it belongs to me.

The CPP file has a similar comment (usually just copied&pasted from the header with a small modification):

 // TimerThread.cpp -- A thread that calls a callback based on a system
 // ---------------    timer.
 // September 22, 1999 -- Copyright Sunir Shah. All rights reserved.
The rationale behind this format is simple: The trick with a file header is to explain why the file exists and to get you to the information quickly. Anything else is overhead, so make sure that it never has to change and it is easy to write.

By the way, I typically write all my classes in C++ in this manner:

  1. Create header file.
  2. Write header file file header. :)
  3. Write the header guards.
  4. Define the basic class. (lots of more steps in here, obviously)
  5. Create CPP file if necessary, copying the file header.
  6. ...
It keeps me focused on the goal.

Indeed, since I consider CrcCards to be a massive amount of paper pushing (compared to SelfDocumentingCode), this is my solution. The header provides the class and role. The methods are the responsibilities. The collaborators if within the encapsulation barrier are clearly indicated between instance variables and method signatures. External collaborators are indicated by the role.

Another real life example:

 // CriticalSection.h -- Critical section class
 // -----------------
 // March 20, 1999 -- Copyright Sunir Shah. All rights reserved.
 //                   (
The description is very redundant, I admit. But that's because I chose a really good name for the class. I still like writing the description because it forces me to think beyond the name even if there's nothing more there.

By the way, attentive readers will notice the "file headers" on the SelfDocumentingCode pages. -- SunirShah

I had a strange idea the other night. If programmers were forced to write class descriptions in HaiKu (e.g. RedScreenOfDeath), they'd be forced to be succinct and descriptive. Complicated classes don't lend themselves to Haiku, either, so simplification will be necessary. They'd also be forced to think about the class description very hard before they start coding it, especially in totally nonlinear ways. This might lead to better, more creative solutions. If you wrote a Haiku to describe the entire system, you might just get a SystemMetaphor ForFree. --ss

A strange idea indeed. I *like* it. --DanielKnapp

Are FileHeaders really necessary? Perhaps all of the data is duplicated.

Filenames aren't on print outs. If they're important to you, use a program that does print them! That way they'll be on every page, too.

Reply on espresso: The description is the most important; class names aren't descriptive enough. This is in the same vein as commenting your methods with a short description. The creation date is important for the copyright banner. Copyright banners aren't necessary technically, but practically they are. Product documentation may not exist if I'm handing someone a utility class, or for projects with multiple authors (more CodeOwnership issues, which is the case in most OpenSource projects). Initials I'm willing to chuck, unless you do CodeOwnership (which I used to do).

The thing to remember about FileHeaders is that OnceAndOnlyOnceIsNotJustForCode.

A three-line header, even if it is a useless ritual, is not something that I would strenuously object to. It might even have value as a ritual; some languages are (slightly) less readable than others, and from my personal experience with C++ I would feel more ill at ease approaching a C++ file without any introductory comments whatsoever than a similarly formatted Java file. It isn't a big difference - a stylistic more than a substantial one - but it is there.

I'm getting rather sick of this ritual, personally. A lot of the redundant information should be stripped, and I think the author initials are more of a sign of personal ego than actually instructive. I still would prefer minimally:

 // MainClass -- One to two-line description (preferably in Haiku ;)
 // Generated by <script name>.    # Only when necessary

Note that dropping the file extension is helpful for mirroring between headers and source modules. Also, since I do most of my C++ coding inside of Perl, the Generated by <script name>. line is useful for others who would like to regenerate the code.

Actually, you're not dropping the file extension--you're changing to referring to the class name instead of referring to the file name.

With Perl (and similarly with main modules in C/C++/Java if I ever manage to get out from underneath the GUI), I usually write something like:

 #  command line [syntax]
 # Description of script.

-- SunirShah

 /* vim:ft=objc:
  * $Id: filled out by cvs $
  * Short description of the file's contents.
  * TODO: things I'd otherwise forget

$Id:$ is one of the cvs "features" whose presence makes merging branches much noisier. The real conflicts are obfuscated by reams of conflicts in $Id:$ lines. Some people turn off $-token expansion when merging, which renders your $Id:$ lines misleading after a merge. Just a negative to weigh when considering using $Id:$ widely.

Also, TODO only reminds you when you actually look at that file. I sometimes put TODOs in my file, and forget to remove the reminder after I've fixed the problem more times than I'd like to admit.

View edit of September 2, 2004 or FindPage with title or text search