Let's talk about the exceptions to the rule.
Everyone knows their code should be written in a way that makes its function obvious. We break it up into chunks with singular concerns to form pure functions. Much of our time is spent naming these functions in a way that will clue the reader in to what's going on. The code we write is clean, tidy, and clever in a way that keeps LOC down.
In a perfect world this would be enough, and 2 years (or months (or weeks)) from now you'd be able to come back to your code and know exactly what's going on. Everyone also knows that our world is not perfect.
Our jobs do not exist in a vacuum, nor does our code. We interact with product managers, designers, and other developers to reach a goal. More often than not, between the plan and execution of that goal, compromises are made. Achieving the perfect solution cannot always be justified given the cost. Other times, legacy code or data force us to add a translation layer or do something that looks or feels ugly. God forbid a stakeholder says something has to be a certain way or else!
Okay, so what's my point? Sometimes we need a way to explain ourselves and the concessions we've made to accommodate externalities. One of those ways is the oft-hated code comment.
Before you write a comment
We'll get to the star of our show soon, but let's talk about alternatives.
- Simplify your code for readability
- Abstract away repeated and necessary patterns/complexities
- Employ excellent naming
- Enforce unobvious business requirements through well-defined tests
- Push back on external forces that cause needless complications
These are all things we should be doing on a daily basis to ensure we're writing awesome software. Some of these can be difficult, but they are preferable to the following.
Last resort
Spoiler alert: It's comments!
So you've gone through all 5 items on the checklist above, but you're still not happy. If you think someone (perhaps yourself) will see this code in the future and ask "Why?", then a comment may help answer their question.
Maybe an API outside of your control returns a nonsensical value. Without context provided by that APIs documentation, it's confusing. You've exhausted all other options, so you add a comment. Cool!
Maybe you've established a pattern or abstraction to accomplish a certain task, but for reasons outside of your control, you need to implement this task differently. If it doesn't make sense to extend your previously created abstraction, it may be helpful to add a comment.
Maybe you've abstracted away a piece of very complex code. You've simplified it, properly named variables and functions, and tested it to enforce requirements, but it's still wicked confusing. Sometimes the only thing that's left is to add a comment. I'm sure this example will be controversial, but at the end of the day, we're humans and not computers. Our brains are slow slow slow. A comment can provide that small cue necessary to keep following along.
Why all the hate?
Comments are generally a sign of poorly written software and/or a lack of understanding. In a perfectly controlled environment, you wouldn't have externalities influencing your code. If everyone was a genius, you wouldn't need to worry about making your code understandable by mere mortals. Good luck with all of that.
Why did Jacob write an entire blog about comments? All of this is super obvious...
Having black and white rules like "NO COMMENTS!" tends to make our jobs/lives easier. Explicit rules mean our brains can forget about the minor details.
The problem is that nothing is black and white.
When we eventually hit a weird situation that makes us question an absolutist rule like "No Comments", we get hung up, and we end up writing code that's less legibile because of it. Maybe it's just me, but I would prefer to know the general rule and the minor details. This can be applied to almost every hot topic. Nothing is black and white, and we should acknowledge that. The last thing we need is more polarization.
← Back to blog