“Oh, my code is self-documenting.” I stared blankly at the junior engineer across from me. Then I stared back at the incomprehensible block of code he had just assured me explained itself. “Well,” I said, “unfortunately I’m not sure what any of this does, so you’re going to have to walk me through it.” At that point in my career, I already had over a decade of experience building mobile apps. I wasn’t new to engineering. What I was new to was the framework this open-source project was built on. And that’s the problem. To him, the code felt obvious. The context was fresh. The decisions were still in his head. To me, it felt unfamiliar and difficult to navigate. Could I have eventually figured it out? Absolutely. Given some time, I could have reverse-engineered the intent and made the changes I needed. But the complete lack of comments or signposts explaining why certain decisions were made turned what should have been straightforward work into something slow and frustrating. This is why “self-documenting code” is a myth. Good code can show you what the system is doing, but it rarely tells you why it exists in its current form. Why this approach instead of another? Why this edge case? Why this workaround that looks unnecessary at first glance? That context doesn’t live in variable names. It lives in comments and documentation. Documentation isn’t about explaining syntax. It’s about transferring intent across time. If you care about maintainability, onboarding, and long-term velocity, writing comments isn’t optional. It’s an act of empathy for the next engineer who has to live in your code. And, sometimes, that next engineer is you six months down the line. Be kind, comment! Happy building (and commenting)! 🚀
Your point about empathy resonates deeply. Commenting isn't just about being thorough, it's about being kind to the next person (including your future self) who has to navigate, debug, or extend the system. It's especially vital in open-source projects, remote teams, or fast-moving startups where tribal knowledge is fragile. Thanks for the thoughtful reminder. In an era of AI-generated code, clear human-authored context might become one of our most valuable artifacts.
Comments in your code is an interesting one. If the code is readable then you shouldn't need comments 🤔. If there is a decision made about a particular way to do something then that should be documented in key decision records. If you're implementing specific functionality, that should be in a ticket that fellow devs can read before they review your code. If years down the line a dev goes through commits on your code they should be able to find the relevant commit and find your reasoning either in the MR or ticket reference -- at least that's how my team works. With the intent -- yes even when we have documentation it can be hard to find if it's not clear where to look 😅
"Self-documenting" code, by definition, cannot document seemingly equivalent formulations discarded for cause. On more than a few occasions I have watched successive generations of developers and maintainers repeat he same course of trying already discarded approaches to issues, only to re-learn the same lessons over and over again
In my experience the best comments explain the why and not the what or how. There isn’t a single rule. I usually go by this ‘why’ principle and add comments if I feel the need to explain why the code exists. Assume the reader does not have your brain, which is a pretty reliable assumption as of 2025. Not sure about 2100. A piece of code no matter how good, cannot explain why it exists. Comments sometimes help fill this gap. Places that comments are not useful to add are usually framework specific entry points like app.get(‘/‘, fcn). No point documenting these standard calls or signatures.. But if you are writing some smart algo or business logic you cooked up in your head, it better have some brief comments to go along. It’s just not nice to future maintainers to have to guess or work hard to figure out why it was done that way. The thing to be careful about is not writing comments that just say literally what the code does. The code is already doing that lol. Comments that get into nitty gritty minutia get outdated pretty soon. Finally, remember ELI5 like what Feynman preached, if you can’t explain your code via code or comments to someone without your context, that code is likely not suitable for human maintenance.
Going through my Tech Residency -- and building out the architecture for the company my team is creating -- has made this lesson hit hard. ‘Self‑documenting code’ disappears the moment context fades. Good documentation isn’t about explaining syntax; it’s about preserving intent so the next engineer doesn’t have to reverse‑engineer your thought process. It’s become non‑negotiable for me. The more I grow in this field, the more I see documentation as an act of respect for your future teammates - and for your future self.
Sorry, but I think you just haven’t read self-documenting code. It should be clear from the function calls what a procedure does, and from your data types what your domain models; and that should remain the case through every abstraction. Alan Kay has an excellent talk on this somewhere on YouTube. He uses a graphics rendering library as a case study iirc. The SICP authors have a similar approach, which they describe as building the language up to your domain
Documenting intent somewhere is really important. It can be helpful in the code, or externally, or both. People often forget that someone else is likely to be maintaining their code one day, as others have pointed out. I learned this lesson the hard way when my future self forgot why I wrote something the way I did. I learned to have empathy for the poor sucker (me) who had to figure out why I did what I did.
Sorry, but comments in your code are just refactorings that the developer is too lazy to perform. Code can be self-documenting, but it takes work and discipline. Also, code should be simple and readable and not clever. Clever is never easy to read and is always ego driven.
Interactive Aptitude, LLC•212 followers
3moI don't know your exact situation, but in my experience what you are describing is an indication that the code needs to be cleaned up, not that it needs documentation to supplement it's lack of cleanliness. In fact, overzealous documentation is generally a flag that someone "made it work" but hasn't "made it right" quite yet (Kent Beck). Documentation that only has to explain "why" (as you mention above) and doesn't have to explain "what" is one signal (necessary but not necessarily sufficient) that the code is "self documenting".