Code cannot and should not be self documenting at scale. You cannot document "the why" with code. In my experience, that is only ever used as an excuse not to write actual documentation or use comments thoughtfully in the codebase by lazy developers.
Be intentional about how AI changes your codebase
31–40 of 123 posts
Re: Be intentional about how AI changes your codebase
#32Code cannot and should not be self documenting at scale. You cannot document "the why" with code. In my experience, that is only ever used as an excuse not to write actual documentation or use comments thoughtfully in the codebase by lazy developers.
this always starts out right but over the years the code changes and its documentation seldom does, even on the best of teams. the amount of code documentation that I have seen that is just plain wrong (it was right at some point) far outnumbers the amount of code documentation that was actually in-sync with the code. 30 years in the industry so
large sample size. now I prefer no code documentation in general
Re: Be intentional about how AI changes your codebase
#33[dead]
Re: Be intentional about how AI changes your codebase
#34[dead]
Re: Be intentional about how AI changes your codebase
#35My intentionality is that I'll never let it make the changes. I make the changes. I might make changes it suggests, but only upon review and only written with my hands.
I think this style of work will go away. I was skeptical but I now write the majority of my code through agents.
+1 for this, once you have a solid plan with the AI and prompt it to make one small changes at a time and review as you go, you could still be in control of your code without writing a single line
Re: Be intentional about how AI changes your codebase
#36Code cannot and should not be self documenting at scale. You cannot document "the why" with code. In my experience, that is only ever used as an excuse not to write actual documentation or use comments thoughtfully in the codebase by lazy developers.
this always starts out right but over the years the code changes and its documentation seldom does, even on the best of teams. the amount of code documentation that I have seen that is just plain wrong (it was right at some point) far outnumbers the amount of code documentation that was actually in-sync with the code. 30 years in the industry so large sample size. now I prefer no code documentation in general
Are there any good systems that somehow enforce consistency between documentation and code? Maybe the problem is fundamentally ill-posed.
Re: Be intentional about how AI changes your codebase
#37"Every optional field is a question the rest of the codebase has to answer every time it touches that data,"
This is a beautiful articulation of a major pet peeve when using these coding tools. One of my first review steps is just looking for all the extra optional arguments it's added instead of designing something good.
Re: Be intentional about how AI changes your codebase
#38Earlier quoted context omitted.
I don't think testing the product alone is good enough, because when you give it tests it has to pass it prioritizes passing them at the expense of everything else — including code quality. I've seen it pull in random variables, break semantic functions, etc.
Oh, no. I test. Each. and. Every. Step. I use a test harness, and step through the code, look at debug logs, and abuse the code, as much as possible. Kind of a pain, but I find unit tests are a bit of a "false hope" kind of thing: https://littlegreenviper.com/testing-harness-vs-unit/
[dead]
Re: Be intentional about how AI changes your codebase
#39Because of the way that I use AI, I am constantly looking at the code. I usually leave it alone, if I can; even if I don't really like it. I will, often go back, after the fact, and ask for refactors and documentation. It works. Probably a lot slower than using agents, but I test every step, and it is a lot faster than I would do it, unassisted.
I don't think testing the product alone is good enough, because when you give it tests it has to pass it prioritizes passing them at the expense of everything else — including code quality. I've seen it pull in random variables, break semantic functions, etc.
[dead]
Re: Be intentional about how AI changes your codebase
#40Page not rendering well on iPhone Safari. Good content tho!
[dead]