Get Commentary - Table Of Contents - Coding Guidelines

You should comment wherever you can - put comments that explain what you're doing, and if you're doing something tricky or unique be sure to explain that, as well. A good goal is to have 1 comment for every 1-4 lines of code.

Comments are generally formatted as either block comments (also called prologue comments or stream comments) or line comments (also called inline comments). Block comments delimit a region of source code which may span multiple lines or a part of a single line.

How to comment Code: Primarily, a single "block" comment should be placed at the top of the function (or file) and describe the purpose the code and any algorithms used to accomplish the goal. In-line comments should be used sparingly, only where the code is not "self-documenting".

Use clear and concise language. Comments should be written in clear and concise language. Avoid using jargon, slang, or complex vocabulary. Avoid personal notes, remarks, or jokes. Generally, a good rule of thumb when it comes to code comments is: less is more.

Comments rules Always try to explain yourself in code. Don't be redundant. Don't add obvious noise. Don't use closing brace comments.

Comments should explain why code is written the way it is, rather than explaining what the code does.

Comments should occur in the following places: The top of any program file. This is called the "Header Comment". ... Above every function. This is called the function header and provides information about the purpose of this "sub-component" of the program. ... In line.

Write clear and concise comments that explain the "why" behind your code. Avoid stating the obvious and focus on complex logic. Use descriptive variable names and update comments when you change code. Consider future readers and avoid over-commenting.