8th Light: Day 95 + 1

14 May 2016 . 8thlight . Comments #apprenticeship #8thlight #software #code-smells

Code smells: Comments

A method is filled with explanatory comments. - sourcemaking.com

Comments in code can be created with good intention, such as explaining what a code block does. However, it is generally better practice to change the code structure to make the comments unnecessary.

The best comment is a good name for a method or class.

Why are comments bad? Comments bloat software and make it difficult to read when reviewing code. If the language allows it, docstrings are a much better way to explain what a method is doing.

Comments can be useful in certain situations, such as:

  • explaining why something is being implemented in a particular way
  • explaining complex algorithms that are unable to be simplified further
  • adding FIXME statements when exporing/spiking to go back and fix/change before commiting to version control

Use your best judgement when adding comments to code.