Difference between revisions of "Cpp Coding Standards/CODEDOC"
m |
|||
| Line 2: | Line 2: | ||
How to document code. There are two kinds of code comments: Interface documentation to be extracted from a documentation tool. This will be called “documentation” in the following. And comments between code lines, those will be called “comments” here. | How to document code. There are two kinds of code comments: Interface documentation to be extracted from a documentation tool. This will be called “documentation” in the following. And comments between code lines, those will be called “comments” here. | ||
---- | ---- | ||
| − | === | + | === Summary === |
==== ClassResponsibility ==== | ==== ClassResponsibility ==== | ||
Start the documentation of each class with a concise statement about its responsibility. | Start the documentation of each class with a concise statement about its responsibility. | ||
| Line 13: | Line 13: | ||
==== Format ==== | ==== Format ==== | ||
In documentation, adhere to the documentation tags and format as described in http://tools.openoffice.org/autodoc/HowToWriteDocumentation-Cpp.html. | In documentation, adhere to the documentation tags and format as described in http://tools.openoffice.org/autodoc/HowToWriteDocumentation-Cpp.html. | ||
| + | ---- | ||
| + | === Explanations === | ||
| + | |||
---- | ---- | ||
[[Category:CodingStandards]] | [[Category:CodingStandards]] | ||
Revision as of 18:08, 27 November 2006
Contents
Code Documentation
How to document code. There are two kinds of code comments: Interface documentation to be extracted from a documentation tool. This will be called “documentation” in the following. And comments between code lines, those will be called “comments” here.
Summary
ClassResponsibility
Start the documentation of each class with a concise statement about its responsibility.
ClearFunctionBehaviour
In function documentation, do not comment the obvious. Do not repeat information that is in the function name or parameter types or names. There may well be functions that need no further documentation.
Do document, when any of the pre- or postconditions of a function is not unambiguously clear. Document, when the behavior in error cases is unclear.
Format
In documentation, adhere to the documentation tags and format as described in http://tools.openoffice.org/autodoc/HowToWriteDocumentation-Cpp.html.
