Following the lead of Java's javadoc program, C++ professionals have adopted the practice of creating web pages from source code documentation; I call these 'docucomments' to distinguish between internal-only comments. Some groups have adopted 'javadoc' style, while others have adopted 'triple-slash' style used in C# programming. Docucomments appear mostly in C++ header files.
You have a choice: C++ or Java style docucommenting. Always use Java's @param, @return and other 'tags' to document the 'signature' of a function (method). Choose your coding style and copy the chosen template files for use on projects (and labs).
The Doxygen open source tool generates documentation for C++ source code from either of the two docucomment formats (javadoc and triple-slash). The CS4 coding standard, 2009 edition, has been updated for doxygen.
The shell script, http://www.cs.rit.edu/~cs4/pub/touch-header, produces a skeleton header file following triple-slash format. That can help jump-start source files in C++.
Alternatively, you can use one of the template files below to craft your own file skeleton. The Doxyfile configuration file produced the example documentation in the doc/html directory; the generated output shows both docs and code.
CxxTemplate.h and CxxTemplate.cpp are 'triple-slash style' C++.
CppTemplate.h and CppTemplate.cpp are 'javadoc style' C++.
We want a program's code to be CONSISTENTLY documented and formatted,
LAB code supplied to you exhibits older, non-docucommented style,
and you must edit or add to the supplied lab code.
A Chameleon Coder edits EXISTING files and maintains the style of that existing code; the evolved code blends in with the existing code. For NEW files added to a set of older lab files, you may choose to apply a newer, more current style.
CodingRecommendations.txt has my opinions of C++ code formatting. -- bks