问题
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...
回答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.
回答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.
回答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.
回答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.
回答5:
I used to like putting version control keywords in the header of file. But recovered from that affliction. :) For two reasons:
- Nobody put comments in that are of any use. You always wind up looking at the diffs reported by the version control system.
- It creates a nightmare in trying to diff large filesets because the keywords create differences that are the only difference in the file.
回答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.
回答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.
回答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.
回答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
回答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).
回答11:
i generally only add any "comment info" when... i don't think i'll remember or its not obvious what something is doing or when i release the source code and i actually want others to be able to use/learn from it.
回答12:
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.
回答13:
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.
回答14:
A copyright statement for my client ;-)
回答15:
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.
回答16:
I use Subversion. Here's what I like to put near to the top.
$Id$
$HeadURL$
That substitutes the revision, last editor, and then the location of the file in the repository. Although I always work from working copies, this lets me print/email a file and look at it later to know exactly where it came from. $HeadURL$ especially is nice because it tells what project and branch the file is in and how to get to it (nice with larger nested subpackages and the like).
Agreed on the uselessness of big manual comment blocks — although docstrings/Javadocs are recommended — and on automatically appending the commit log.
It sounds like some of you are using terrible VCSes, if you are getting diffs or merge conflicts generated by the keywords themselves. Subversion handles it well.
来源：https://stackoverflow.com/questions/318835/do-you-add-information-to-the-top-of-each-hpp-cpp-file