Commenting Code: Describe Why, Not What

I love well-comment code and am a little perplexed by engineers who live by the “comment as little as possible” mantra. Maybe I’ve just written a lot of bad code, and comments have helped tremendously when I look back to refactor it! What defines well-commented code, though? In my experience, the key is to describe why you did what you did rather than what you did. Let’s Compare if (x === 0) { displayTheComponent(); } A what comment for this might be: “if x is 0, display the component” A why comment for this might be: “if the user hasn’t ever made a purchase, we’ll show them a special UI component explaining some benefits of purchasing” Obviously, this is a contrived example but hopefully it explains the concept. The first what comment is completely useless to anyone with more than a week of engineering experience; we can look at the code and tell what it’s doing. The why comment is better. If we return to this code two years from now and wonder, “Why did we do this?” we’ll know! Next time you’re reviewing a PR, just meandering through old code, or when you’re refactoring unfamiliar code, pay attention to your thought process. I think you’ll notice that you often ask yourself, “Why are we doing this here?” What is Sometimes Useful in Complex Scenarios What comments can be useful from time to time. Particularly when code gets complex, some what comments sprinkled here and there may be helpful. I like using code-foldable regions to keep complex code organized, and I often write what comments in those regions: #region get user data #endregion #region transform user data #endregion [ Avoiding files and especially functions that get larger than a few hundred lines is often the best approach to keeping code simple, but sometimes complexity is unavoidable ] I’d love to hear your take on commenting code. There are so many different styles and opinions that it’s still an open debate in my mind what works best in a team scenario!

Feb 28, 2025 - 04:14

I love well-comment code and am a little perplexed by engineers who live by the “comment as little as possible” mantra. Maybe I’ve just written a lot of bad code, and comments have helped tremendously when I look back to refactor it!

What defines well-commented code, though? In my experience, the key is to describe why you did what you did rather than what you did.

Let’s Compare

if (x === 0) {
  displayTheComponent();
}

A what comment for this might be: “if x is 0, display the component”

A why comment for this might be: “if the user hasn’t ever made a purchase, we’ll show them a special UI component explaining some benefits of purchasing”

Obviously, this is a contrived example but hopefully it explains the concept. The first what comment is completely useless to anyone with more than a week of engineering experience; we can look at the code and tell what it’s doing. The why comment is better. If we return to this code two years from now and wonder, “Why did we do this?” we’ll know!

Next time you’re reviewing a PR, just meandering through old code, or when you’re refactoring unfamiliar code, pay attention to your thought process. I think you’ll notice that you often ask yourself, “Why are we doing this here?”

What is Sometimes Useful in Complex Scenarios

What comments can be useful from time to time. Particularly when code gets complex, some what comments sprinkled here and there may be helpful. I like using code-foldable regions to keep complex code organized, and I often write what comments in those regions:

#region  get user data

#endregion

#region  transform user data

#endregion

[ Avoiding files and especially functions that get larger than a few hundred lines is often the best approach to keeping code simple, but sometimes complexity is unavoidable ]

I’d love to hear your take on commenting code. There are so many different styles and opinions that it’s still an open debate in my mind what works best in a team scenario!