4.0 Source Code Files
C++ style comments (//) are preferred for single lines or small numbers of lines. C style comments are ok for large , blocks of comments (/* */).
4.4.2 File header comments (GL)
These comments should provide an overview of the module including its relationship to other modules. Items that affect the rationale for the current design should be documented at the top of each file.
4.4.3 Class header comments (GL)
These comments should provide an overview of the class including its relationship to other classes.
4.4.4 Function declaration comments (GL)
Comments for methods or functions should document the purpose of the function, the allowable values for the inputs and outputs, including pre- and post-conditions. They should also describe exception conditions and side effects.
4.4.5 Variable declaration comments (GL)
If not completely obvious from the choice of variable name, try to document what the variable is used for.
4.4.6 Function implementation comments (GL)
For non-trivial functions or methods, it is often useful to put a synopsis of the function at the beginning of the impelementation.
4.4.7 Implementation notes (GL)
Comments should explain "why" a piece of code is written as it is, NOT recap "what" is being done. Always document a function or method before coding; if you can't clearly explain it, you probably should not write it.
4.4.8 Put copyright notices in all C++ files. (R)
The following copyright notice should be put into all .h .cc and other source code. There is a template file (copyright.h) that can be copied into the source code.
/* static const char copyright[] = "Copyright (c) 199X, Scientific and Engineering Software , "
"Inc. All rights reserved worldwide. This program or documentation "
"is supplied pursuant to and its use is governed by a license "
"agreement from Scientific and Engineering Software , Inc. and "
"contains confidential information of Scientific and Engineering "
"Software , Inc. Disclosure and copying are subject to "
"restrictions contained in such agreement and any subsidiary "
"agreement."; */
4.4.9 Put source code repository key words in all C++ source files. (GL)
The following tag should be at the beginning of all source code files. Note the first form is for interface files and the second for implementation files.
RCS:
*.h: // VersionId: $Id$
*.cc: static const char* const VersionId = "$Id$";
SourceSafe (PC):
*.h: // VersionId: $Header: $
*.cc: static const char* const kVersionId = "$Header: $";
Note that some data files will not allow inclusion of comments, hence will not allow version control ids.
4.4.10 Always keep comments up-to-date (R)
Do not change code without updating the comments. Review comments for correctness prior to checking in source code changes.
Generated with CERN WebMaker