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.

// Grab the remote content and transform it to JSON

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

// 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.

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

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s