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.
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
The good thing about having documentation in the (version-controlled) code is that it allows you to retrace when it was correct (using git blame or equivalent), and that gives you background about why certain things are the way they are. I 100% prefer outdated documentation in the code to no documentation.
It's not a massively complex AI monstrosity (it's from 2018 after all) or a perfect solution, but it's a good jumping off point.
With a slight sprinkling of LLM this could be improved quite a bit. Not by having the agent write the documentation necessarily, but for checking the parity and flagging it for users.
For example a CI job that checks that relevant documentation has been created / updated when new functionality is added or old one is changed.
interesting that they don’t mention doctest which has been a python built-in for quite a while.
It allows you to write simple unit tests directly in your doc strings, by essentially copying the repl output so it doubles as an example.
combined with something like sphinx that is almost exactly what you’re looking for.
doctest kind of sucks for anything where you need to set up state, but if you’re writing functional code it is often a quick and easy way to document and test your code/documentation at the same time.
right but docstrings are documentation, so if your doctest is working, then at least that part of the documentation is correct.
Even without doctest, generating your documentation from docstrings is much easier to keep updated than writing your documentation somewhere else, because it is right there as you are making changes.
If the documentation and code could be in-sync, then the documentation would just be code, like type hints. But good documentation that the parent is talking about cannot be in-sync.
Programming languages can't understand semantics, and that's why we program in the first place. I can't tell a computer "I would like a program to achieve this goal", instead I have to instruct it how to achieve the goal. Then, I would need to document elsewhere what the goal is and why I'm doing it.
LLMs change that, we can now legitimately ask the model "I would like a program for this goal". But the documentation is lost in the code if we don't save comments or save the prompt.
Git commits are also a good source of documentation. They shouldn't describe what we're doing, because I can just read the code. But often, I come across code and I'm thinking "why are we doing this? Can I change this? If I change it, what are the side effects?" If I'm lucky, the git blame will answer those questions for me.
I am not saying it doesn't matter because it does, but how much does it matter now since we can get documentation on the fly?
I started working on something today I hadn't touched in a couple years. I asked for a summary of code structure, choices I made, why I made them, required inputs and expected outputs. Of course it wasn't perfect, but it was a very fast way to get back up to speed. Faster than picking through my old code to re-familiarize myself for sure.
We cannot get full documentation on the fly, though. We can get "what this does" level of documentation for the system that AI is looking at. And if all you are doing is writing some code, maybe that is enough. But AI cannot offer the bigger picture of where it fits in the overall infrastructure, nor the business strategy. It cannot tell you why technical debt was chosen on some feature 5-10 years ago. And those types of documentation are far more important these days, as people write less of the code by hand.
This is the same discussion that goes round ad nauseum about comments. Nobody needs comments to tell us what the code does. We need comments to explain why choices were made.
Keeping the documentation in the repo (Markdown files) and using an AI coding agent to update the code seems to work quite well for keeping documentation up to date (especially if you have an AGENTS.md/CLAUDE.md in the repo telling it to always make sure the documentation is up to date).
Code can only ever document "what" by definition, never "why". If it could document "why", then no computer programmers would exist. So, we have to supplement the "why" using natural language. There's a 100% loss conversion there when we convert it to code.
I find it to be more difficult. Especially if I can't pane the files in view comfortably (ie. beyond 2 or 3 it gets significantly harder to work across them).
Some frameworks or coding styles really lean into having lots of tiny files. That necessitates a more complicated directory structure for the project. Locating files eventually tends to requires search capability rather than being able to look through the tree in a sidebar.
None of this is "hard" per se but I find the opposite is nicer to work with typically.
the top 5 comments on this thread are from accounts that are around 10 years old each. What gives you any reason to believe this is an astroturfing campaign?
Estimation is an art, not a science. It's always going to be a judgement call by the engineers tasked with giving them to management. Taking all of the factors from this article and beyond can and should go into making that judgement call.
I always tell my teams just skip the middlemen and think of estimates as time from the jump. It's just easier that way. As soon as an estimate leaves an engineer's mouth, it is eagerly translated into time by everyone else at the business. That is all anyone else cares about. Better said - that is all anyone else can understand. We humans all have a shared and unambiguous frame of reference for what 1 hour is, or what 1 day is. That isn't true of any other unit of software estimation. It doesn't matter that what one engineer can accomplish in 1 hour or 1 day is different from the next. The same is true no matter what you're measuring in. You can still use buffers with time. If you insist on not thinking of your labor in terms of hours spent, you can map time ranges to eg. points along the Fibonacci sequence. That is still a useful way to estimate because it is certainly true as software complexity goes up, the time spent on it will be growing non-linearly.
I second this. If you don't close the loop, if you don't keep track of what you estimated and how long it took, how are your estimates going to get better? They aren't.
> Not a great regulatory move, in my opinion.
> But I really wish ad companies would implement this rule across the board.
You don't see how these are conflicting viewpoints? What do you think would compel a company to act in some way that is not in line with its short term financial interests? Sheer luck?
Long term financial interests, mostly. I know the ads run on my network will never, under any circumstance, be allowed to appear without a skip button within 5 seconds. Immediately, if possible. The only conditional is when the skip button appears, not if. And that's divorced from the copy; the component that plays the ad doesn't care what copy is running, it controls the skipability.
If an advertiser does not like those terms and is willing to forgo my users for that position, more power to them. I have every confidence that I will still find advertisers and, in my experience, they will be higher quality advertisers for the demographics of my users. Artists tend to advertise in cheap space that they know other artists will be viewing. You get the idea.
What has me curious is why you see those two as conflicting viewpoints? I didn't need a government to regulate me. Just common sense and care for my users. I'm not going to subject them to noisy or obnoxious ads, nor am I going to subject them to content that may not be suitable for everyone, and so I'm also not going to subject them to overly long ads. It seems, to me, that you have a profound lack of faith in the platforms you use. Which I can understand as a practical realization about the current apex platforms. But I don't know why it would blind you to the possibility of reasonable people acting reasonably.
I see them as conflicting viewpoints because as a general rule companies do not focus on
> Long term financial interests, mostly.
It's great that you as an individual feel otherwise (I do too), but there are larger macro forces at work which compel firms to act the way they do: pursue short term growth at all costs. The counter-balance to this is either a strong regulatory environment, or a hope and prayer that a majority of companies suddenly gain a strong CEO who feels otherwise and is not obligated to satisfy shareholders who don't. Only a few such CEOs come to mind, and they're looking increasingly short for this world.
Well, you can already see my hope and prayer. I don't think it's unlikely to come about as you do; rather I think that in the long run the market will eventually reward the better behavior, as any good capitalist believes. But rest assured that I also want a strong regulatory environment. The only winning long term strategy is to be twice as forgiving as you are punitive. So that means forgive a lot, but still punish when applicable. Given that, I think good laws derived from sound reason, voted on by a free public are a great way to both guide and punish all entities, including corporate ones. I just don't think that this regulation is the kind that is derived from sound reason.
I think there are so many issues with this type of regulation that circumvention will be inevitable and, like with so many other things, lead to a worse outcome overall. I think good regulation will look different altogether, but it's hard for me to imagine what it will look like. My best guess is that it will target different choke points, or target them in different ways. Maybe like... subsidies for content creators that enforce a 5-second limit on ads? It's not something many have control over now, but a platform would instantly become more attractive to content creators if they were allowed to dictate that.
Seems like that would have some sour ramifications as well, but it's just off the top of my head. The point is, I'm not against regulating the hell out of these giant industries, or these industry giants. I'm all for it. I just want it to actually work/make things better.
Account created 16 hours ago posting highly dubious AI hype? This user is almost certainly part of the intense astroturfing campaign likely financed by Anthropic that has been ongoing for days/weeks now.
Have others not noticed the extremely obvious astroturfing campaign specifically promoting Claude code that is mostly happening on X in recent days/weeks?
reply