4 ms·

> That said, it was amazing to just see it go through the requirements and implement modules full of organised documented code that I didn’t have to write Smal

> That said, it was amazing to just see it go through the requirements and implement modules full of organised documented code that I didn’t have to write Small side remark, but what is the value added of the AI generated documentation for the AI generated code. It's just a burden that increases context size whenever AI needs to re-analyse or change the existing code. It's not like any human is ever going to read the code docs, when he can just ask AI what it is about.

nisegami 1y ago
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.
infecto 1y ago
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.
felixgallo 1y ago
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.
- manwe150 1y ago
  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
  - r_murphey 1y ago
    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.
- Der_Einzige 1y ago
  I promise you that token context rot is worse than the gains from added natural language explanations
  - felixgallo 1y ago
    This hasn't been my experience.
  - alwillis 1y ago
    Keep in mind each Claude subagent gets its own context.
aosaigh 1y ago
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.
weego 1y ago
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
- skydhash 1y ago
  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?)
  - Xss3 1y ago
    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.
r_murphey 1y ago
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.
cpursley 1y ago
Claude's proclivity for writing detailed comments and inline comments and very near perfect commit messages is one of the best things about it.
SatvikBeri 1y ago
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.
lurking_swe 1y ago
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.
- fragmede 1y ago
  > 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.
  - lurking_swe 1y ago
    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.
jaggederest 1y ago
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.
- xcf_seetan 1y ago
  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.

nisegami 1y ago

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.

infecto 1y ago

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.

felixgallo 1y ago

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.

manwe150 1y ago
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
- r_murphey 1y ago
  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.
Der_Einzige 1y ago
I promise you that token context rot is worse than the gains from added natural language explanations
- felixgallo 1y ago
  This hasn't been my experience.
- alwillis 1y ago
  Keep in mind each Claude subagent gets its own context.

aosaigh 1y ago

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.

weego 1y ago

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

skydhash 1y ago
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?)
- Xss3 1y ago
  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.

r_murphey 1y ago

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.

cpursley 1y ago

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

SatvikBeri 1y ago

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.

lurking_swe 1y ago

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.

fragmede 1y ago
> 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.
- lurking_swe 1y ago
  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.

jaggederest 1y ago

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.

xcf_seetan 1y ago
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.