Do you add information to the top of each .hpp/.cpp file? [closed]

Question

When creating a new C++ header/source file, what information do you add to the top? For example, do you add the date, your name, a description of the file, etc.? Do you use a structured format for this information?

e.g.

// Foo.cpp - Implementation of the Foo class
// Date: 2008-25-11
// Created by: John Smith

One team I know embeds CVS commit messages to the foot of each file, but I'm not sure I want to go this far...

Answer 1

Information about who created a file and when and who edited it and when is all in source control. If your team has good practices around check-in comments, then you'll know the reasons for each change too. No need for comments for that stuff.

I think it's 100% legit - wise, even - to put a comment block, as long as is necessary, explaining the purpose of the class/module. When the next person goes to change it, they'll have a better idea of the overall vision and whether this file is the appropriate place for their change.

Some shops put copyright notices and other legal folderol in source file comments. This strikes me as just silly - if your (non-OSS) source code has made it onto someone else's servers without your knowledge or permission, a copyright notice is probably not going to deter them from doing anything with it. IANAL, YMMV.

Answer 2

Don't. Most of the stuff can be retrieved from the versioning system when needed so it's redundant to add. That would leave you with the description of the content of the file but that's part of the class documentation most of the time (or at least the documentation of the specific type).

I don't do any of those, but then again, I don't like the cruft.

Answer 3

We're required to put copyright information at the top of each file. I think dates, authors, and the name of the file is a waste of time.

We also have our source control system append check-in comments at the bottom of each file. I initially hated the change log, but over time I learned to like it. It really helps when merging changes.

Answer 4

I include the file name, a brief description of the file's purpose, and a $Id$ tag for CVS or Subversion purposes. File creator and date of creation can be found by checking the repository, so it's not needed.

File name is included because depending on what you're using to edit the file, that might not be entirely apparent when you're editing it. The description can be used to determine if a bit of code belongs in the file, or if it should be moved to another. And of course, $Id$ gives you last change time, and last editor.

Embedding check-in messages is only useful when the message is useful, and only if the file is updated once and a while. Including every message will simply bloat the file to the point where there's more comments describing changes than there is actual code. Best to leave that to the repository as well; often it's only a short command line to get the file's check-in log.

If you're stuck with a revision control system that can't keep history for moves and copies, in that case just reference the original file and its version number. Of course, if you're using a system that was created sometime in this century and not the last, that shouldn't be an issue.

Answer 5

I used to like putting version control keywords in the header of file. But recovered from that affliction. :) For two reasons:

1. Nobody put comments in that are of any use. You always wind up looking at the diffs reported by the version control system.
2. It creates a nightmare in trying to diff large filesets because the keywords create differences that are the only difference in the file.

Answer 6

Originally answered here, but since deleted: 134249

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.

At the time I worked for a large defense company, and we had draconian coding standards. 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 7

I don't embed the date because it's redundant. If someone wants to know the date a file was created don't trust the author, trust your source control system. It should be the defintive answer for the date of creation.

I'm definately not against embedding check in messages though. Those are pretty useful.

Answer 8

We use our RCS to automatically stamp the following on the file:

Copyright,

RCS file name,

Date modified,

Author of last change,

RCS revision number

I think this is very convenient. I really like having the file name automatically populated in each file, because it makes searching the solution for files very quick.

Answer 9

This is what i normaly put at the top of files:

///////////// Copyright © 2008 DesuraNET. All rights reserved. /////////////
//
//   Project     : [project name]
//   File        : [file name]
//   Description :
//      [TODO: Write the purpose of ... ]
//
//   Created On: 11/12/2008 2:24:07 PM
//   Created By: [name] <mailto:[email]>
////////////////////////////////////////////////////////////////////////////

and i set up a macro in vis to do add it in and fill in default info when i make a new file

Answer 10

If you're using CVS, check out it's keyword substitutions. They will help automate embedding that information.

Personally I stick this at the top of all of my source files:

// $Id$

Other informative comments I embed to be parsed with doxygen, if they relate to something specific (the file, the class, a type, etc).