Skip to content

Documentation

Write comments in US English (CGC16001) recommendation level 1

Write code documentation in US English (CGC16002) recommendation level 1

Dokumentiere alle von außerhalb verfügbaren Typen und Members (CGC16003) recommendation level 2

Documenting all types and members, which are accessible from outside (assembly, namespace, class, …). Use the common way to document that kind of code, depending on your programming language (javadoc for java, XMLDoc for .Net and so on). This way other developers can get the most out of your function without knowing the concrete implementation.

Furthermore, you can use tools to create professionally looking documentation.

Write documentation with other in mind (CGC16004) recommendation level 2

Write the documentation with other in mind. Assume they will not have access to the full source, the requirements and specifications, so try to explain how to get the most of the functionality of your code.

Avoid inline comments (CGC16005) recommendation level 2

If you feel the need to explain a block of code using a comment, consider replacing that block with a method with a clear name.

Don't use comments for tracking work to be done later (CGC16006) recommendation level 2

Annotating a block of code or some work to be done using a TODO or similar comment may seem a reasonable way of tracking work-to-be-done. In reality, nobody really searches for comments like that. Use a project management system to keep track of leftovers.

Another way is a combination of the usage of a work item in a project management system, and a related TODO comment, with a reference to that work item.

Only write comments to explain complex algorithms or decisions (CGC16007) recommendation level 1

Try to focus comments on the why and what of a code block and not the how. Avoid explaining the statements in words, but instead help the reader understand why you chose a certain solution or algorithm and what you are trying to achieve. If applicable, also mention that you chose an alternative solution because you ran into a problem with the obvious solution.


Last update: 2021-09-26
Back to top