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...
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.
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.
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.
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.
If you're using CVS, check out it's keyword substitutions. They will help automate embeding 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).
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.
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.
I usually include a description of the purpose of the code found in that file. Everything else seems to be handled elsewhere: dates and comments in source control, etc.
Everyone is saying that your source control will have the date and programmer info, but that isn't always true. I worked in a shop that used Source Safe, and it was fine until someone decided to move a file to a different location. At that point, it essentially became a new file according to SS, and no previous history existed.
Perhaps because of that, the programmer name and date were automatically added to the comment section at the top of the file. When there got to be more than about 10 entries, we'd strip out all of the middle ones, leaving only the original date and author, and the current information.
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
We use MSVC & VSS and have a plugin that adds any comment you specifiy at check-in to the file that's being checked in as a comment. It's very convinient to look at the top of the CPP file to find out the bug-tracking ticket number that a change was made for.
I used to like putting version control keywords in the header of file. But recovered from that affliction. :) For two reasons: