Code Comments should answer “Why?”

Reviewing and debugging a lot of code gives you some interesting insight. In the past when I’ve written code comments I’ve often answered what and how.

[code]// Grab the remote content and transform it to JSON[/code]

That comment for example is useless. Anyone can read the code and see what it’s doing and how it’s doing it.

[code]// We need to re-fetch the remote content here because our cached version may be stale after a write operation.
//We know this by checking the $potentionally_stale_cache variable.[/code]

With this comment we know why we’re refreshing the cache and can understand if this code is still needed or might not be because of changing requirements.

Leave a Reply

Your email address will not be published. Required fields are marked *