Discussion on: 10 practices for writing readable code

syncsynchalt profile image
Michael Driscoll

I've found a better way to pitch "remove comments": When you see a one-liner comment, there are two opportunities for its removal:

  1. if the comment is above the function or method definition, maybe the function can be renamed in a way that removes the need for the comment
  2. if the comment is within the function or method, maybe the code block that it's commenting can be extracted into its own function/method with a name that will reflect what the comment is trying to say

In this way our comments become reflected in the code itself, making the code more readable/understandable, more resistant to comment rot, and more meaningful to tools like IDEs.

One more statement: Not every comment can/should be removed, this is not absolutist advice.