Stop Commenting Your Code!

(This doesn't refer to JavaDoc or other externally facing documentation - see my post linked at the bottom about that)

It just isn't good practice.

Coding

Good practice is:

  1. Writing single responsibility and modular code
  2. Naming well
  3. Testing
  4. Deleting code as often (or more often for older projects) as writing new code

I'll refer you to the SOLID principles for dogma to follow if that's your thing. However, you don't need to understand those terms to follow them.

Why is the rule of commenting code in so many developers’ minds?

Honestly, it is the easy way out. It is much easier than coming up with good names (actually surprising different to many).

Also, refactoring to polish up code for “the next person” many times gets left out. The next shiny thing came along, more and more features were piled on the developer, or he simply forgot.

Beware of comments

It is nearly impossible to tell if the comment you found is to be believed and trusted or a relic from code that no longer exists, or doesn't function the same.

Believe the tests!

This is where the truth is told. Tests run with the builds (they should anyhow), so they must be correct.

If there are no tests, you have a bigger problem than comments and need to take the leadership initiative to demand testing begin immediately.

Thanks for reading!

Comments powered by Talkyard.