Jump to the navigation menu

Comments can lie. Code can't.

How often have you need code like this?

// Returns true.
return false;

Whilst a comment like this could have been true when it was written, the code can change independently of the comment - making them out of sync and the comment no longer true.

As the comment is not evaluated or executed, there isn't a way to validate whether it's still correct, so whilst it could be, it may not be.

Comments should describe why the code is needed, not what it does.

If a comment describes the functionality, it can be refactored and extracted to a class, method or function - a.k.a. self-documenting code.

But, if you want something that will alert you if the functionality changes, look into automated testing.

If you have a passing test that suddenly starts to fail, you know the behaviour has changed.

- Oliver

Was this interesting?

Sign up here and get more like this delivered straight to your inbox every day.

About me

Picture of Oliver

I'm an certified Drupal Triple Expert with 18 years of experience, a Drupal core contributor, public speaker, live streamer, and host of the Beyond Blocks podcast.