File Headers

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.
 //                       (sshah@intranet.ca)

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:

Filename: Identifies the major class in the module. Occasionally helper classes get thrown into a C++ module violating the one module/one class guideline, but this easily directs me to what I care about the most. Also, when windows fly around or when printing, it gives you a quick, known place to look for the filename.
Description: This is the main reason to have the header. It identifies the role of the class. If you can't describe the purpose of the class in one or two sentences, the class is too complicated. Even if it contains the same words as the class name, just with punctuation added, it can serve as a ZenSlap to those not finding the proper interpretation.
Dashed line: Makes a nice, simple visual element to distinguish the major class name from the rest of the text. More importantly, however, it provides a second line for the description to run onto. It should be noted that this is the limit for descriptions: two lines. Short and sweet.
Creation date: It obviously provides a creation timestamp for copyright purposes, but it does more than that. It provides a quick clue to the context that existed at the time the module was created. If you've been working on a project for long, you know the history of the influences on the project. And you know your own history naturally. Not as accurate as source control, but quick and maintenance free.
Initials: Author of the module. A non-intrusive signature. It's better than a full name for small projects, I feel, because it is less personal, more egoless than a full name. Use a full name if you wish though. Once again, source control is more detailed, but this is quick and maintenance free. Obviously if you're really opposed to any form of CodeOwnership, then authorship is a vile foreign concept to be avoided, so you can ditch this.
Copyright banner: Well, it's a copyright banner.
E-mail address: If this is publicly released code, then I have to be contactable.
The lack of anything else: Maintenance free, simplicity and clarity are the goals here.

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:

Create header file.
Write header file file header. :)
Write the header guards.
Define the basic class. (lots of more steps in here, obviously)
Create CPP file if necessary, copying the file header.
...

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.
 //                   (sshah@intranet.ca)

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.

Filename: It's the file name. Most editors display it.
Description: Some people feel that a class description means that your name isn't descriptive enough, or that your class is too vague. Even so, couldn't this just become a class comment?
Creation date: In the version-control system.
Initials: In the version-control system.
Copyright banner: Necessary. In the US and some other places, original works are automatically copyrighted, but if the author fails to protect this copyright - for example, distributes the code in such a way that people might mistake it for public-domain - it goes away. Even when they're part of a package, files are a natural unit for redistribution without the awareness of the original author. No lawyer would ever suggest that this be left out.
E-mail address: If this is publicly released code, you have some sort of product documentation. I bet your email address is already in there. Is there really a need to repeat it in every class?

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:

 #!/usr/bin/perl
 #
 #  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.