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.
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.
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.
“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.
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.
I'm with you in not wanting to see these types of comments in my code. I aim for each revision of the code to stand on its own, and not reference its past or future. There are exceptions and nuances, of course, such as TODO comments or comments related to ongoing migrations. I try to keep these short and reference tasks in the issue tracker, which are going to be more useful to anyone who happens to be reading the code.
I've heard the argument that leaving these comments in, helps support future AI code generation. In this example, it was important to you at the time you made the change that create_* functions have defaults, so having this in the code captures that knowledge for later agents. It's similar to a more general argument that you should leave (correct) AI-generated code alone because it will be easier for the AI to "understand" code it generated that your modified version of it.
I see the validity in these arguments, but I don't think we should be so deferential to these models. The first part of this comment ("Now create_background params have default values") is completely redundant with the function signature and as no place in the code. The second part ("the same as create_screen") is genuine knowledge that is worth capturing for the agent, but it should be captured at a higher level doc about the codebase, rather than tacked onto some arbitrary function as a comment.
It's strange that he shows the graphs with the age of vulnerabilities going up without any real commentary on it (except to say that it's an argument that the number of bugs is not close to zero). I'm not so sure—I think a deeper analysis needs to be done that accounts for the fact that the project itself is aging and also accounts for code churn.
For example, if bugs were introduced and detected via a mostly uniformly random process, but most of the code was written in the early part of the project's lifecycle, then you would expect the age of bugs to go up over time (since there is less young code). Even if the code addition rate was constant, if developers were producing fewer bugs over time, then the age of the bugs would increase, since older code would be buggier.
It's been a while since I taught anyone to juggle, but I generally disrecommended scarf juggling. It's fine if you want some quick validation, but the hand movements are so different from balls/bags that I don't think the skills are transferable.
I prefer the method described in the original post. Just start with one ball and get that right, then two, then three. It's a bit like the Karate Kid, though. Students don't find it as satisfying because they want to jump ahead before they've got the movement down.
The scarves I use, as I mentioned in another thread, are actually weighted. They fall more like a traditional ball, just significantly slower. I’ve found that this works pretty well for teaching, but of course everyone learns differently.
1) I would generally use BBSes daily. Probably for an hour in the evening or however long I could tie up the family phone line. I would log into two or three, read and respond to messages. Very much like reading email at the end of the day. I forget what I started with, but once I found ZTerm for Mac I did not go back.
https://en.wikipedia.org/wiki/ZTerm
2) I'm honestly not sure how I found my first. Possible I found some number at the local library, possible a friend in high school gave me one. Once you found one, you could learn about others from that one. There was a real culture of different sysops trying to get you to use their board (but only up to a point because it used phone lines)
3) It's really difficult to know. There was no equivalent to web search or a way to see what everyone else was doing. I'd expect the popularity followed some kind of power law, but everyone used a different subset of boards.
4) It's difficult for me to remember. Probably much shorter messages that would seem "simple" by today's standards.
Team CLI. I generally think we should build tools that are usable by humans and agents alike. An anti-pattern is having to use an agent to do something because you didn't build a human-accessible one. Another anti-pattern are MCP (Model Context Protocol) interfaces that are not managing any context.
That said, MCP could be an effective way to sandbox what an agent can do with a tool. Also, it seems plausible to me that a tool that actually provided information to a model via the MCP protocol could be more useful than a CLI tool which operates in the "silence means success" mode of most unix CLI tools.
Basically, make a design choice for _reasons_ and not just because you like that TLA of the option you picked.
This is a really nice take and matches my experiences as well. It also calls out one of the biggest incongruity of this current age: the sudden desire from management to have good specs and documentation for the benefit of the coding assistants.
For the first time in my career, I've seen an engineering org add "improve tech documentation" as a high-level goal. It makes me sad that it was never worthwhile to do for the engineers, but now we need it for the coding assistants who can't tell that our docs really out of date. On the flip side, the coding assistants will actually read the docs, unlike many engineers.
This is such a strange take. The definition of "magic" in this post is apparently "other people's code" and it even admits that that no practical program can avoid depending on other people's code. I think what the author is really saying that they like to minimize dependencies and abstractions, particularly in web client development, and then throws in a connection to coding assistants.
I don't see it, either the notion that other people's code is to be avoided for its own sake nor that depending on LLM-generated code is somehow analogous to depending on React.
Python crossed the chasm in the early 2000s with scripting, web applications, and teaching. Yes, it's riding an ML rocket, but it didn't become popular because it was used for ML, it was chosen for ML because it was popular.
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.
reply