What information to put in comments at the top of a sourcecode file?

Question

What information do you consider worth to put in the comment at the beginning of a sourcecode file?

All I could think about was the name of the author and perhaps the date the file was created (although I'm not to sure if there is any useful value to this information).

[EDIT] To clarify, I don't mean comments before a class, but at the first lines of the file, before include statements and what else. Like

/**
 * Author:    Name
 * Created:   11.05.2009
 * 
 * (c) Copyright by Blub Corp.
 **/

Answer 1

• Copyright
• Original author(s)
• License (if it's open-source)
• One-line purpose statement or description
• Further overall documentation and usage examples

Edit: Changed Author(s) to Original Author(s)

Answer 2

if the file is going to contain some very common class / functionality which can be understood with reasonable common sense, then you dont really need to put much in the description otherwise if the source code file is a class / function very specific to the project or is encompassing a complicated logic, then you should give a high level overview & purpose of the source code file.

Answer 3

File Encoding! (utf-8)

# -*- encoding: utf-8 -*-

Especially if you plan on sharing your code with someone else in some other part of the world at some point.

Answer 4

What to put in the file header:

• Library/component that source code is part of
• Copyright details
• Brief and meaningful description of class(es) in source file

What NOT to put in the file header:

• Anything that duplicates low level logic which is part of the code itself. This can lead to maintenance problems if it isn't updated when the source code changes.

• Author name(s). Why?

  • In the world of revision control systems, while there may be an initial author of some code, eventually ownership becomes blurred. This is especially true when code enters the maintenance phase of the life cycle where owners can change regularly.
  • All code eventually becomes "community wiki" after enough changes ;-)
  • Would you want your name associated with all of the code forever, knowing full well that you will not be responsible for the code until its death?

• Creation and last changed dates. This is for similar reasons as list above. Revision control includes this information - why duplicate it in the header, making more work for yourself and risking leaving inaccurate information in the comment when things inevitably change?

Answer 5

with all the above also put sort detail of the purpose of the code in that file also something u think can be helpful in debugging and understanding the functionality.this help in maintainence and support.