you are viewing a single comment's thread
view the rest of the comments
[–] 18 points 2 years ago (1 child)

The best explanation I've ever heard is:

Comments should state the 'Why' never the 'What'.

  • source
  • parent
  • hideshow 2 child comments
  • [–] 1 point 2 years ago

    There are some cases though where the code is just complicated for reasons outside of your control, in which case "what" comments are good - but they should never be taken at face value, but only used as a first step in understanding the code. There's a significant risk of the code not actually doing what the comment says.

  • source
  • parent