Instead of writing code comments that decay and mislead, let LLMs generate documentation on-demand and fail the build when code is too obscure for them to explain.

Yegor256 Blog offers insights, opinions, and discussions on software development, engineering practices, and technology trends. Covering topics such as object-oriented programming, code simplicity, and software design principles, Yegor256 Blog provides resources for developers and tech enthusiasts. Developers can explore unconventional ideas, challenge conventional wisdom, and broaden their perspectives on software craftsmanship through Yegor's blog posts and essays.

Yegor's Blog

Code comments decay and mislead over time, creating more problems than they solve. Instead of writing manual documentation, LLMs can generate explanations on-demand from the code itself, ensuring freshness and accuracy. By integrating LLMs into the build pipeline to measure a Code Interpretability Score, teams can enforce readability as an objective quality gate—if the LLM can't explain the code with high confidence, the build fails. This approach eliminates the need for comments entirely, forcing developers to write inherently clear, self-documenting code.

Comments Considered Harmful in the Age of LLMs

Bro, no big app can survive without docs and comments. This is another vibe coding post that will make new coders shoot their feet.
If your comments where like “this fn that sums a and b” you didn’t need comments before LLMs. Moreover wrong comments suggests change o underlying functionally, which will make programmers investigate legacy code. Lack of comment will suggest new/needed code for everything and LLMs will not be wiser. how many times did your ai said that your code is old? You will be waiting for your libs to be depreciated to get any warning.

LLM can explain what you wrote, but it can’t explain why.

Reminds me of something I read a long long time ago that’s stuck with me. It went along the lines of “write comments before you write code, write in plain, simple words what your intention is. If you can’t explain what you’re going to do in plain terms, then maybe you haven’t thought enough about it…”
I always found that interesting.

<ol>
<li>I agree on writing less comments because they tend to lie over time.</li>
<li>It takes me longer to ask an LLM to explain code than to just read and understand it myself.</li>
<li>Some important comments, like why certain decisions were made, can only be provided by the original developer and aren’t obvious from the code itself.</li>
<li>I made a post about comments a few month ago as well, please read it, i think it will help you: <a href="https://dly.to/BYrCUNECHf4" target="_blank" rel="noopener nofollow">https://dly.to/BYrCUNECHf4</a></li>
</ol>
Cheers ✌️

Bad Idea, the job of “Intention Comments” is to document external requirements and decisions like “This memory Layout has to match the SPSs-Dataframe” that any reader of just the Code (especially LLMs who can’t go look at the SPS) can’t know about.