Like many coders, I am a proponent of writing self-documenting code. The more I have worked with intentional code that omits unnecessary or misleading comments, the more efficient I have been as a software engineer. I read clear code and I understand what is going on.
However, regardless of whether I have spelunked self-documenting code or code with a girth of extraneous comments, both styles often omit why something is being done when it’s not obvious. Maybe an API you’re interacting with has a bug, so you have to do things in a roundabout or undocumented way. Maybe there is a non-obvious edge case that your main conditional branch code covers that another programmer would expect to be solved in a more conventional manner. Maybe you made a calculated business decision for a particular user experience when other sites behave differently.
Make it obvious why a non-obvious approach was taken. Save your fellow engineers and your future self from re-exploring the explored, re-arguing the argued, and re-deciding the decided.
Ian Lotinsky 
“Save your fellow engineers and your future self from re-exploring the explored, re-arguing the argued, and re-deciding the decided.”
Very well said sir. I wish this had been the case at my work.
This might be the most thoughtful post about comments that I have ever read. I’m usually pro “commenting everywhere” because I do not think that too much commenting is as harmful than not enough, but commenting only the “why” definitely establishes a nice balance. Thanks!
Join the Hacker News conversation at https://news.ycombinator.com/item?id=5331387
I’m a big fan of commenting only what the code cannot say, not simply what it does not say. The difference is subtle though significant in the hands of the right developer.
Sometimes the ‘why’ is indeed that single comment when code simply can’t explain it clearly enough. We have very strong exception handling on a solution we’re currently developing, yet there are one or two places where we bury exceptions. It’s a requirement of any developer who buries an exception to have a very solid business case for doing so, and it must be documented.
catch (UnableToAssociateUserWithAffiliate) {
// TB: at this point in registration, we’ve logged all of the affiliate details and we just failed associating the user with this affiliate – we don’t want the user to see a registration error just because of this (when it is easily fixable and we’ve already been notified of the problem)
}
kinda thing.
Code couldn’t in that instance have given over the full intention of why that exception would have been buried even though there’s a very clear case for it.
I always attempt to have the code say exactly what (and indeed why), and only really fall back on comments when the code cannot say that.
Agree with your post. Here is a detailed response from my side: http://blogs.agilefaqs.com/2013/03/07/inline-comments-in-the-code-is-a-smell-but-document-the-why/
A couple of months ago I stopped writing code comments about “how” and started writing them only about “why”. It has really helped me, not to mention co-workers who have to maintain my code.
The only thing I would add is that there are two benefits to be had here:
1. Write about “why”: your co-workers don’t have to re-explore.
2. *Don’t* write about “how”: fewer comments makes it easier to find the important ones.
This is something I have been preaching for years. It is only when you know the reason why something was done that you have the power to change it. There are many other places in technology where the reason why is very important…
Project management. For example, 2 years after an IT project was done people wonder “Why did they choose B instead of A? It makes no sense.” So they change to A and a few weeks later they discover why B was chosen when something breaks. Properly documenting projects, including the reason why things were done can save a huge amount of time later.
Software development requirements (very close to what you wrote above). When defining the product requirements, don’t just assume it is obvious why something is needed. State the reason why explicitly. It saves lots of time later, especially when you start to prune requirements to fit in a minimum viable product.
Finally when defining requirements for purchasing tech products, e.g. ERP, CRM etc. systems or even selecting data centers. If you don’t know why a requirement is listed, you really can’t change it, or even properly evaluate product features against that requirement. Where this really shows up is on large project like ERP when somebody leaves the company. Now you ask “Why did they want that?” If you don’t know the answer and change the requirement, you might miss the particular use case they were wanting to resolve.
Couldn’t agree more. Well said Ian.
This is probably the best example of where I commented the “why”:
https://github.com/wpappstore/wp-app-store/blob/85135e3b7de6123ae1e15ac1c3de8f24b58ad11f/classes/wp-app-store.php#L543
Thanks for the kind words everyone. I’m glad this post resonated with people.