File header or general comment

Question

Does anybody have a nice well structured starting comment for a file? I'm looking for something that looks nice, either fancy or very professional.

By general comment I mean the comment at the top of a file showing your name and purpose of the file. Like this one:

/********************************************************           
    * hello -- program to print out "Hello World".         *   
    *                                                      *   
    * Author:  FirstName, LastName                         *   
    *                                                      *   
    * Purpose:  Demonstration of a simple program.         *   
    *                                                      *   
    * Usage:                                               *   
    *      Runs the program and the message appears.       *   
    ********************************************************/

Answer 1

doxygen format?

/*! \file hello.cpp
\brief program to print out "Hello World"

Created: 2009-11-21 by FirstName, LastName \n
Modified: \n
*/

Answer 2

For C#, Stylecop enforces a header that looks like this

// <copyright file="filename.cs" company="Company">
// Copyright (c) 2008 All Right Reserved
// </copyright>
// <author>Mr blah blah</author>
// <email>[email protected]</email>
// <date>2009-11-21</date>
// <summary>File description.</summary>

You can configure the required company name in the copyright tag.

Answer 3

For Java, I prefer the following style (but these points can be applied to other languages too):

• If you would like to include some copyright stuff, do in the first one or two lines. Keep it short. If you have something more to say about this, do it in some README file or on your product's web site.

• Do not include any metainfo such as filename, last modification date, @author or @version tags. Tools like Subversion can keep track of such things much better, and duplicating this kind of information just adds unnecessary work to keep them in sync.

• Start the javadoc of your class with a sentence that summarizes its main function.

• No need to use captions like Purpose or Usage, just explain what you have to say in a few paragraphs. Forms and fields are great if a script needs to process them, but not so much if people will read them.

So to sum it up, I use something like this:

/* Copyright 2002-2009 Foo Ltd. All rights reserved. */

package foo.bar;

/**
 * This class does this or that.
 *
 * Now you can go into the details, try to be professional here by writing a
 * few clear, articulate paragraphs, not by drawing fancy ascii boxes.
 *
 * @see foo.bar.OtherClass
 */
public class MyClass {
   ...
}