Difference between revisions of "Cpp Coding Standards/CODEDOC"
From Apache OpenOffice Wiki
m (Cpp Coding Standards/Topics/CODEDOCU moved to Cpp Coding Standards/Code Documentation: Improve Cpp_Coding_Standards structure.) |
m |
||
| (6 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
| − | == Code Documentation == | + | == Code Documentation (CODEDOC) == |
| − | How to document code. There are two kinds of code comments: Interface documentation to be extracted from a documentation tool. This | + | ''How to document code. There are two kinds of code comments:'' |
| − | + | * ''Interface documentation to be extracted from a documentation tool. This in the following is called “documentation”.'' | |
| − | + | * ''Comments between code lines. Those are called “comments”.'' | |
| − | + | ||
| − | + | ||
| − | ==== | + | ===== Describe the Class Responsibility <span id="ClassResp">(ClassResp)</span> ===== |
| − | + | Start the documentation of each class with a concise statement about its responsibility. [[/ClassResp|->Details]] | |
| − | + | ===== Clarify Function Behaviour <span id="ClearBehave">(ClearBehave)</span> ===== | |
| + | In function 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.<br> | ||
| + | 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.<br> | ||
| + | [[/ClearBehave|-> Details]] | ||
| − | ==== Format ==== | + | ===== Format <span id="Format">(Format)</span> ===== |
| − | 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 the code documentation [http://tools.openoffice.org/autodoc/HowToWriteDocumentation-Cpp.html HowTo].<br> |
| − | + | [[/Format|-> Details]] | |
| − | + | ||
| − | [[ | + | |
---- | ---- | ||
| − | [[Category: | + | [[Category:Coding Standards]] |
Latest revision as of 09:02, 23 May 2007
Contents
Code Documentation (CODEDOC)
How to document code. There are two kinds of code comments:
- Interface documentation to be extracted from a documentation tool. This in the following is called “documentation”.
- Comments between code lines. Those are called “comments”.
Describe the Class Responsibility (ClassResp)
Start the documentation of each class with a concise statement about its responsibility. ->Details
Clarify Function Behaviour (ClearBehave)
In function 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.
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.
-> Details
Format (Format)
In documentation, adhere to the documentation tags and format as described in the code documentation HowTo.
-> Details
