What to write in the header comments of a code file?

Question

I'm just starting a new green-field development project, and I'm trying to set some standards. I know that a lot of codebases have header comments in every code file with a copyright notice and other gumph. Is this a necessary or useful practice?

For example, I don't think putting the name of the author or dates of modifications is useful, because our source control system tracks that for us. On the other hand, a simple copyright notice might be useful, or even a requirement.

At this point in time, and for the forseable future, we don't intend to distribute the source code in anyway.

What (if anything) do you put in the header of your code file?

Answer 1

I always put a copyright notice or at least the GPL in the headers of my source. I also include a brief summary of what the code is intended to do and any tips or points to remember when using the code.

Answer 2

Please don't go overboard and put too much information in the header. The last company I worked for (which wrote software for controlling nuclear reactors) had a crazy amount of things in the header - lists of authors, dates, updates, #includes, variable names, function names (and return values) - and that's just what I can remember off the top of my head!

This all came from old coding standards that were developed before source control was used - but even with proper source control they said they had to have the headers (and keep them updated) as they were they only accepted proper trail.

Answer 3

I'd say nothing.

That stuff it mostly bloat and gets in the way,

If you want to include a licence then include it as a separate file, I've seen last edited by comments and original author comments they should be handled by source control.

Keep your code clean.

Answer 4

The Microsoft standard header looks something like this;

// <copyright file="AuthenticationType.cs" company="SharpSTS">
// Copyright (c) 2007, 2008 All Right Reserved, http://sharpsts.com/
//
// This source is subject to the Microsoft Permissive License.
// Please see the License.txt file for more information.
// All other rights reserved.
//
// THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY 
// KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
// PARTICULAR PURPOSE.
//
// </copyright>
// <author>Barry Dorrans</author>
// <email>[email protected]</email>
// <date>2008-06-10</date>
// <summary>Contains a base, abstract class for an AuthorisationPolicyProvider</summary>

Answer 5

Copyright information and "All Rights Reserved", just to make the suits happy.

A brief description of what the contents of the file are supposed to do.

Perhaps some kind of versioning info (via your source control's macro expansion, whatever it may be), just in case you wind up finding source code sitting all alone in a directory. If you integrate it with your code then you can make your code spit out the versions of some/all of the files that were in that particular executable (or whatever). Personally, I find the latter to be too much information, but that's up to you.

Answer 6

If at this point you don't intend to distribute the code, place the minimal amount of information, like a short description of the file's contents.

You can always add more stuff with a script later on, for all files. For now, keep it clean.

Answer 7

Along with the others, I agree: "Do the simplest thing that could possibly work."

Answer 8

I would only put two things:

• licensing/copyright information
• comments required by documentation-generating tools (i.e., the comments have to be in the header to work - otherwise, they should go in the definition files)

anything else is unnecessary fluff that won't be maintained, and will eventually become worse than nothing at all.

@robintw - I totally agree. I currently work for a large defense company, and we have the most draconian coding standards you can imagine. If you followed them to the letter (and most people don't), most of your headers would be composed mostly of that meaningless fluff. Doubly worse is that the exact same fluff is required to be placed in source files as well, which means two copies of the fluff gets out of date and becomes misleading.

Answer 9

I too cast my vote for keeping it simple. All of the licensing, version, etc stuff should be kept in a single file somewhere else. The reason for this is that if any of it changes, you will need to go back and update each file individually. You could at least be smart and have a script that does this automatically, but you still have the problem of a bloated header file.

If you insist putting anything in there, you might give a small description for the intended context of the interfaces/classes outlined in the header file.

Answer 10

For C++ header files I tend to put

-*-c++-*-

on the first line so that Emacs knows it's a C++ file (otherwise the .h extension means it gets treated as C, which doesn't really matter except that it gets put in a different group of files and you can't use tabs to switch between them with Xemacs).

Apart from that, I'd agree with most other people here. A short description of what the file is for, a copyright notice, maybe $Id$, that's about all. Definitely not the name of the person who created it and the date - if anyone really cares, that's what CVS is for. But I must admit I tend to include the filename, which is entirely pointless.

Answer 11

What do you want to see in other people's headers? Do you want to wade through pages of copyright cruft? Or do you want to see a concise but informative module overview with links to more detailed documentation?

I think you can rely on your own experience to decide what is useful and what is not.

Answer 12

For my code, I keep to a fairly small list, though slightly longer than some people above would like. But, once the file is created, I seldom alter it, apart from the copyright date range:

/*
@(#)File:           $RCSfile: stderr.c,v $
@(#)Version:        $Revision: 8.29 $
@(#)Last changed:   $Date: 2008/06/02 13:00:00 $
@(#)Purpose:        Error reporting routines
@(#)Author:         J Leffler
@(#)Copyright:      (C) JLSS 1988-91,1996-99,2001,2003,2005-08
@(#)Product:        :PRODUCT:
*/

My code was originally under SCCS control; I migrated to RCS prior to Y2K to avoid problems with SCCS. I use the @(#) so that the what command spots the lines, and leaves ident (the native RCS equivalent of what) also spots the lines. The :PRODUCT: stuff is related to the way I distribute source - this file is embedded into all sorts of products, and the current product name is edited into the code as I distribute it -- consider that a personal quirk. Some of my files have an explicit @(#)Licence: :LICENCE: line in the header - most do not.

I'm thinking of migrating to other VCS (probably git, but not decided for sure yet). At that point, I'd have to review the automatic version information -- if the VCS does not support such things, ... well, I might not use it (I regard it as very important, and is my biggest gripe about Clearcase, which I use at work) ... or I'd have to rethink the header information. You should do the same before blindly adopting what I suggest.

I have similar headers for other languages. I also have a script that generates a skeletal file with my standard header in it, so I can write newdoc somefile.c somefile.h and not need to do very much to it beyond fill in the purpose of the code in the file. I have a script for editing the copyright date list, too. (Actually, a lot of my programming work style could be summarized by 'I have a script for it'.)

I also embed version strings into executables. For example, one command in my bin directory is linkpath and I can see what code is in it (my command line prompt is 'Black JL:` because my machine's name is 'black'):

Black JL: what linkpath
linkpath:
        $Revision: 2.34 $
        $Date: 2008/07/26 04:06:31 $
        $Id: stderr.h,v 8.22 2008/08/09 20:12:49 jleffler Exp $
        $Id: linkpath.c,v 2.34 2008/07/26 04:06:31 jleffler Exp jleffler $
        $Id: dirname.c,v 2.5 2008/02/11 08:44:50 jleffler Exp $
        $Id: errhelp.c,v 8.4 2008/08/09 20:13:12 jleffler Exp $
        $Id: stderr.c,v 8.29 2008/06/02 13:00:00 jleffler Exp $
        SunOS 5.10 Generic January 2005
        $Id: jlss.h,v 2008.2 2008/06/03 10:13:42 jleffler Exp $
Black JL:

I find that useful, too.

Answer 13

If it is boiler plate text that goes in the front of every file, use some sort of a guard mechanism. e.g. in the start of all my java files I put:

/*
= LICENSE =
*/

Then, I can run a regular expression substitution over my files to replace/update it, so it'll end up looking like:

/*
= LICENSE =
This is my code, hands off!
= LICENSE =
*/

One advantage is, as long as you remember to stick the guard in when you start a new file, you can worry about what text should go in there later.

The other nice thing is if you update the license text for whatever reasons (e.g., adding a new year, updating a URL) you just re-run the substitution task and it'll fix up all your files in the one hit, rather then having to go in and edit each by hand.

I use ant's replaceregexp task to handle this.

Example ant code that loads the license details from a text file:

<property name="guard" value="= License ="/>
<loadfile property="origlicensetext" srcFile="license.txt"/>
<echo file="target/license.txt"
  message="${guard}${line.separator}${line.separator}${origlicensetext}${line.separator}${guard}"/>
<loadfile property="licensetext" srcFile="target/license.txt"/>
<replaceregexp
  match="${guard}(.*${guard})?"
  replace="${licensetext}"
  flags="ims"
>
  <fileset dir="src" includes="**/*"/>
</replaceregexp>

It'll work for any sort of code file that supports multi-lined comments. Not sure how you would deal with something like a shell script file where every line has to start with a "#", but I'm sure it could be done with a little ingenuity. I've not needed to do that yet.

Answer 14

10 minutes ago I looked at the code file I am working on right now. I saw the top of the file, with no comments whatsoever, and was briefly tempted to put something there. And then it occurred to me that in 25 years of programming I must have produced Terabytes worth comment headers (maybe not literally), but never actually used them once (maybe also not literally, as in the 80s there was no other place to track changes).

Today, I give code files meaningful names so that people know what they do (takes care of the description) and I use source control that tells me who changed what when and why. So, unless someone tells me that he wants a comment header, and what's supposed to be in it, there is none in my code.