written once, looked at 100 times.

I try to prompt-enforce no line by line documentation, but encourage function/class/module level documentation that will help future developers/AI coding agents. Humans are generally better, but AI sometimes needs a help to stop it not understanding a piece of code's context and just writing it's own new function that does the same thing

But comments like that are most likely to be WHAT the code do. Which is rarely useful (naming your identifiers better can help with that). When I need a comment, I'm actually looking for WHYs, aka design decisions. And in this case your prompts are better than whatever comments the agent may add. (Maybe add a summary of the prompts in the commit message?)

This.

Documentation should answer WHYs not HOWs.*

* = Unless the how is a complex, opaque, or obscure algorithm. Then sometimes a written explanation can help. Sometimes that can be as simple as the name and variant, e.g. Dijkstra with k shortest path routing.

I’m not sure I agree that I’ll never look at the code. I think it’s still important to know how the code is working for your own mental model of the app. So in this case I’ll be testing and reviewing everything to see how it’s implemented. With that in mind it’s useful for me as well as serving as context for the AI. That said, you may be right.

Doc strings within the code could be helpful for both humans and AI. Sometimes spoken word intent is easier to digest then code and help identify side effects for both human and AI.

frequently your session/context may drop (e.g. claude crashes, or your internet dies, or your computer restarts, etc.). Claude does best when it can recover the context and understand the current situation from clear documentation, rather than trying to reverse engineer intent and structure from an existing code base. Also, the human frequently does read the code docs as there may be places where Claude gets stuck or doesn't do what you want, but a human can reason their way into success and unstick the obstacle.

I promise you that token context rot is worse than the gains from added natural language explanations

This hasn't been my experience.

Keep in mind each Claude subagent gets its own context.

From Claude -r you can resume any conversation at any previous point, so there isn’t a way to lose context that way. As opposed to compact, which I find makes it act brain dead afterwards for a while

Oh God yes, I wish there were better tools to help one curate and condense a context when one finds that sweet spot where it's writing great code.

It's entirely possible that the parameters that get activated by comments in code are highly correlated with the parameters involved in producing good code.

Often someone will have to maintain the code. Whether the maintainer is a human or an AI, an explanation of the intent of the code could be helpful.

Claude's proclivity for writing detailed comments and inline comments and very near perfect commit messages is one of the best things about it.

Examples. Examples are helpful for both humans and LLMs, especially if you have a custom framework or are using an unusual language. And I find I can generate ~10 good examples with LLMs in the time it would take me to generate ~3 good examples manually.

This is sort of like asking “why do pilots still perform manual takeoffs and landing even though full autopilot is possible?” It’s because autopilot is intended to help pilots, not replace them. Too much could go wrong in the real world. Having some skills that you practice daily is crucial to remaining a good pilot. Similarly, it’s probably good to write some code daily to keep skills sharp.

1) when your cloud LLM has an outage, your manager probably still expects you to be able to do your work for the most part. Not to go home because openai is down lol. You being productive as an engineer should not depend on the cloud working.

2) You may want to manually write code for certain parts of the project. Important functions, classes, modules, etc. Having good auto-generated docs is still useful when using a traditional IDE like IntelliJ, WebStorm, etc.

3) Code review. I’m assuming your team does code review as part of your SDLC??? Documentation can be helpful when reviewing code.

> You being productive as an engineer should not depend on the cloud working.

lol where do you work? This obviously isn't true for the entire industry. If Github or AWS or your WiFi/ISP is down, productivity is greatly reduced. Many SaaS company don't have local dev, so rely on the cloud broadly being up. "Should" hasn't been the reality in industry for years.

Well, the only thing i need to write code is to be alive. No Github or AWS? No problem, have local copies of everything. No Claude? ok, i have local llm to give some help. So, internet is not so needed to write code. No IDE's just a CLI? Sure all i need is a text editor and a compiler/linker working. No computer or electricity? Get a pen and paper and start writing code on paper, will get to the computer when possible. I do not depend on cloud working to be productive.

No pen a and paper? Compile it on fleshware.

It's not a question of what you can do, but where the comfort level reduction outweighs the project importance/pay.

My company deploys everything in the cloud, but we can still do some meaningful work locally for a few hours if needed in a pinch. Out gitlab is self hosted because that’s extra critical.

I continue writing code and unit tests while i wait for the cloud to work again. If the outage is a long time, I may even spin up “DynamoDB Local” via docker for some of our simpler services that only interact with DynamoDB. Our apache flink services that read from kafka are a lost cause obviously lol.

It’s also a good opportunity to tackle any minor refactoring that you’ve been hoping to do. Also possible without the cloud.

You can also work on _designing_ new features (whiteboarding, creating a design document, etc). Often when doing so you need to look at the source to see how the current implementation works. That’s much easier with code comments.

You said productivity is greatly reduced. He said productivity should not stop.

You are making different points.

Leaving aside the value for humans, it's actually very valuable for the AI to provide indexed summary documents of what code goes where, what it does, and what patterns it uses, and what entry points and what it's API conventions are.

This is useful because if you just have Claude Code read all the code every time, it'll run out of context very quickly, whereas if you have a dozen 50 line files that summarize the 200-2000 lines of code they represent, they can always be fresh in context. Context management is king.

The way I use Claude is like first i ask about research about what i want to do, what's new, any little known stuff, etc. As soon i get something i like, I ask Claude to make a specification with everything it needs for making this happen (this is for me to understand how things will be done. Then i ask for an analysis of the specification and ways it can make it short, but in a way it understands the specification and can use it to make things happen. When i got the specification ready, I just upload the specification and ask: start building phase 2. And that's it. It just generates the code, i move it to the ide and start reading and change whatever i want. If i find something diferent from the specification, or a new development, i just update the specification.