Published: 2026-03-09
"Heresy!"
It's not heresy though. It's a good example of how deeply we need to change our thinking about how we write programs in the age of LLM-assisted coding.
Why did we start documenting our code in the first place? The answer to that question seems pretty straightforward. When we returned to our code, it was nice to have a good plain-language summary of what we did and why we did it. And more importantly, when the person returning to our code was someone else, having some notes there to explain the design and purpose of that code was really helpful when debugging or enhancing it.
But those benefits didn't come for free. It took time to write inline documentation. It took more time to update that documentation each time we modified the code. And if someone neglected to update that documentation, it became outdated and sometimes, completely incorrect. Sometimes our bad documentation became worse than no documentation at all.
Moreover, when we were documenting our code, we had no idea whether or not anyone would ever even need that documentation. It might end up being valuable, or it might never be read by anyone. We had to write it anyway, we couldn't predict the future.
Then, LLM-assisted coding came along, and we found we could use it to do much of this documentation busywork for us. The coding assistant could write our inline documentation on demand. It could update it on-the-fly. Coding assistants would generate documentation for us automatically when generating code, usually without even being asked to.
"What a golden age! What a time of right and reason!"
But actually no, having a coding assistant write inline documentation is just plain stupid. We are so conditioned to think "documentation is good" that we're blind to the fact that it's pointless to record documentation inline anymore. As I mentioned above, we don't even know if that documentation will ever be needed for anything. And if it is needed, most of our development tools are LLM-fueled at this point. In my experience, these tools are quite good at analyzing code on the spot and explaining how it works in a dynamic and interactive fashion.
So instead of documenting code when the code is written, generate that information when and if it is needed. And don't store that information right inside the code. If it's needed again later, just regenerate it then. That way, we don't need to worry about keeping any documentation updated. There is no good reason to continue documenting our code like we used to.
Now, a couple caveats. Sometimes we write code that involves some rather complex or convoluted algorithms. It's probably still a good idea to include a brief explanation of those complexities inline. When an LLM is explaining the code for us, those comments will help it generate accurate results. And sometimes we like to include links to certain references or resources that are relevant to the code, we should still put those in there too.
Nonetheless, the overall philosophy of code documentation is completely different now. So, I'm going to say it, for dramatic effect as much as anything:
Documenting your code is bad practice.
I can just feel some folks getting upset at that statement even as I type it. But I'm standing behind it, and I'm pretty sure I can defend it if challenged.
In this article, I'm mostly referring to inline code documentation. I believe the principle can be extended somewhat to other forms of documentation, if not now, then in the near future. But given the technology we have at our disposal today, we can dispose of inline documentation right now.