[nickm12]

During the rise of agentic assistance, I've gotten the advice that "If the generated code isn't what you want, fix the steering, not the code". I've also been advised to not change the sometimes verbose comments and documentation that agents write because "it will help them the next time they look at the code".

I've been skeptical and these guidelines validate this. I continue to document code and write specs as I've always done. If an agent produces poor output or misunderstands, I use that as an opportunity to improve the docs, but in a way that that aims to be accessible for human peers, not the quirks of the current generation of models.

[ckolkey]

One of the oddities of the comments Claude makes is that they are very referential to the current session, or reference now dead/removed code... Which I consider useless. Things like "implement this X way because it's faster than Y" ... But a human reading the code wouldn't know what Y is, or that it even existed necessarily. So, I find myself constantly fixing comments to be less temporarily dependant.

[nickm12]

Yes, I've seen this a bunch too and agree completely. Sometimes I've also see Claude comments reference details about the calling or even code in completely different modules.

There are many reasons I don't like it, but a top one is that it falsely implies that you somehow need to know these details about the removed code/calling code etc to understand this code as its written in this revisions.

[adithyassekhar]

“Code should be self documenting.” I know cliche but if your code does need to do something it usually doesn’t do or has a complex logic or an edge case where it’s no longer following it’s standard flow, add all those as test cases.

If the flow is too complex, inherits from all over the place and you must put that as a comment, ask claude to write a test for that, it’s usually good at those.

[nickm12]

I believe both that code should be self-documenting but also that comments and documentation are a critical part of the code. Comments and documentation explain the functional contract of the code and why implementation choices were made.

Even if you have tests for an edge case, a comment inline with the code that explains why this edge case exists and why it is handled the way it is adds value to the code.

[adithyassekhar]

I agree. I’m talking more about these agents going in and breaking things. They might get some context when a test fails.