Commenting guidelines

Commenting tips and guidelines

Generally, we want to follow these basic guidelines when commenting code:

• Avoid inconsistent indentation
  • All comment should be in line with each other unless they're in line comments for specific lines of code
• Avoid obvious comments
  • If the comment is coded in a self explanatory manor, there is probably no need to write a comment for it
• Have a consistent naming scheme when choosing variable names (use Camel Case consistent with the Java Naming Convention see Naming Conventions)
• Keep sentences within a certain area
  • If you have to scroll to the right of the screen to view a comment, it's probably better to start a new line
• Keep the comments concise and to the point
• Avoid comment structure that would go against our linting rules
• Check that the comment makes sense with respect to the code
  • Don't imply that the code does something other than what it actually does
• Don't commit commented out code to master, unless it's for a very good reason