To be honest, most of these things can happen for poorly documented large codebase. I work on academic research project that have docs that tells you basically that the code is self documented. And give one or two pages about configuring CMake and build the project and another page on how to benchmark the throughout. But the internal quirks and the expected convention you will need to figure it on your own.
New people contributing usually reinvent many things and change global configuration because they don't know they can use something already there.
Ironically indexing the codebase and ask LLM questions about specific things is the best thing you can do. Because the only 3 people who you can ask left the project or are busy and will reply within a week.
> docs that tells you basically that the code is self documented
Anytime someone tells me the code is self-documented I hear "there's no documentation."
The most common programmer's footgun
I don't have time to document
| ^
v |
Spends lots of time trying to understand code
We constantly say we don't have time to document the code. So instead we spend all our time reading code and trying to figure out what it does, to the minimal amount of understanding needed to implement whatever thing we need to implement.
This, of course, itself is naive because you can't know what the minimal necessary information is without knowing something about the whole codebase. Which is also why institutional knowledge is so important and why it is also weird that we'd rather have pay raises through switching companies than through internal raises. That's like trying to fix the damage from the footgun with a footgun.
> why it is also weird that we'd rather have pay raises through switching companies than through internal raises
How does the saying go, something like “show me the incentives and I’ll show you the outcome?”
> That's like trying to fix the damage from the footgun with a footgun.
If you value your money/time/etc, wouldn't the best way to fix the damage from footguns be by preventing the damage to you in the first place by not being there if/when it goes off?
I think your point is well put, I’m just trying to follow your reasoning to a conclusion logical to me, though I don't know if mine is the most helpful framing. I didn’t pick the footgun metaphor, but it is a somewhat useful model here for explaining why people may act the way they do.
The other thing about documentation is that it inevitably goes stale.
So the question becomes: is no documentation better or documentation that can be - potentially - entirely out of date, misleading or subtly wrong, because eg they documented the desired behavior vs actual behavior (or vice versa).
I'm generally pro documentation, I'm just fully aware that internal documentation the devs need to write themselves and for themselves... Very rarely gets treated with enough respect to be trustworthy.
So what it comes down to is one person spearheading the efforts for docs while the rest of the team constantly "forgets" it, until they decide it's not worth the effort as soon as the driving force either changes teams or gave up themself.
There's two helpful and minimal mitigating strategies here
1) dating/versioning
Provides hints that they might be stale if we can identify if they're old. Easy to diff a function between versions when something seems wrong
2) In code documentation (e.g. docstrings)
While not as good as a manual, it's not too difficult to write docstrings *while* coding.
But the unfortunate thing is that you just need to keep documents up to date. Docstrings only go so far.
Also, I'm pretty certain we've all experienced a choice between two tools where our choice prioritized documentation. Docker is a great example (it's even RedHat's business model!). There's many container systems, many that can even do more! But take systemd-nspawn (and vm). Very poorly documented stuff and not many examples to learn from.
I wanted to make that reminder because UX is important to the business.
I think there’s a natural tendency to want to document the process for those who have the work assigned to them, and some folks will self-assign it because they see the value.
Knowledge transfer through technical writing doesn’t always manifest itself if it isn’t part of the work process at the time you have that in your mental context. It’s hard to have that context to write the docs if you’re context switching from working on something else or not involved at that level, so it’s hard to just drop in to add docs if there isn’t some framework for writing ad hoc docs for someone to fix up later.
I don’t have experience at traditional employers though so I can’t speak authoritatively here. I’m used to contracts and individual folks and small business. Having human readable documents is important to me because I’m used to folks having things explained on their level, which requires teaching only what they need and want to know to get their work done. Some folks don’t even know what they need when they ask me for help, so that’s its own process of discovery and of documentation. I’m used to having to go to them where they are and where the issue is, so there was no typical day at the office or out of it. Whatever couldn’t fit through the door, I had to go to myself. I’ve had to preserve evidence of potential criminal wrongdoing and document our process. It taught me to keep notes and to write as I work.
I think most places do have some kind of process for doing this, and I suspect the friction in doing the thing is part of the issue, and the fact that it’s difficult thankless work that doesn’t show up on most tracked metrics is part of the issue.
If docs were mandated they would get done. If someone’s job was to make sure they were done well, that would help. I guess folks could step up and try to make that happen and that might be what it takes to make that happen.
> How does the saying go, something like “show me the incentives and I’ll show you the outcome?”
I think you're trivializing this saying here. The incentives actually suggest you should raise wages of current employees more than new ones. Current ones are more valuable.
Of course, the issue is time. What timeframe are we measuring the incentives at.
You should pay current employees less iff either 1) time doesn't exist (or you are finding the instantaneous optimal solution) or 2) employees are fungible (institutional knowledge does not exist)
Otherwise, you should be trying harder to keep current employees because you recognize the value of institutional knowledge. You don't have to train current employees. Current employers don't have to get up to speed (which usually take a few months and can take years).
It's not a hard equation
Costs:
Existing employee:
+cost of raise
New employee:
+salary of existing employee
+ raise
- onboarding inefficiency * (t_n - t_0)
- existing employee * (time they train)
- costs to interview, hire, etc * (time to hire new person)
So yeah, if time doesn't exist, you're right, it is the incentives. But since it does, I disagree that they are
> the best way to fix the damage from footguns be by preventing the damage to you in the first place by not being there if/when it goes off?
This implies that the footgun will inevitably fire. It also implies you can get out of the line of fire. But you can't get out of the way of a footgun. A footgun is something where you, the gun operator, shoot yourself in the foot.
My argument is that the best strategy is to ,,never fire'' the footgun.
Avhception gives a good visual analogy without using the word footgun[0]
> The incentives actually suggest you should raise wages of current employees more than new ones. Current ones are more valuable.
You should only do this if you have to in order to have better business outcomes. It may be better for the business to not do this, because the current employees will stay even if you don't pay them more, until they don't. So we have to find out what that point they will leave is by not paying some of them more when we otherwise ought to or would otherwise.
> This implies that the footgun will inevitably fire. It also implies you can get out of the line of fire. But you can't get out of the way of a footgun. A footgun is something where you, the gun operator, shoot yourself in the foot.
These are Chekhov's footguns. As you mention in this comment, they do fire, and they will hit whoever is in front of them. They don't only fail when pointed at the feet of the operator. Your wording implies that they will go off in the original comment too. I can't be blamed for the shortcomings of your original metaphorical argument, which I responded to in good faith.
> > That's like trying to fix the damage from the footgun with a footgun.
This implies that the footgun going off is seemingly unavoidable, which leads folks to weird anti-footgun (damage) mitigations, even second footguns. I responded to this phrasing specifically. That's why I argue that the damage of footguns is probabilistic, in that iff footguns usually go off, then on a long enough timeline, they will hit someonesomewhere, and you don't want that to be you, so you should jump ship before it seems like it's unavoidable. I don't see how that is a misreading of the concept or your words, because that is consistent with how a lot of job hoppers I know relate to their work and switching jobs. Even when they do their best, the footguns eventually go off on someone at job sites that allow the footguns to begin with, so it is fair to say that they will go off, but it's uncertain who management will blame or find fault with, so they need not "go off on" the person holding the footgun or even the person who loaded it or pulled its trigger. Those are all different roles/jobs, even though they may be done by the same person at times.
> My argument is that the best strategy is to ,,never fire'' the footgun.
Surely then the second best strategy is to not be there if/when it goes off? We can't count on them not being fired, to my view.
After all, these are Chekhov's footguns, remember?
> You should only do this if you have to in order to have better business outcomes.
Correct. As I explained.
> These are Chekhov's footguns
I think you're confusing "Chekhov's rifle" with "footgun".
A "footgun" is a reference to (shorthand for) the idiom "shooting yourself in the foot." The idiom refers to a self-inflicted problem. Just as how someone may carelessly handle a gun and shoot themselves in the foot.
On the other hand, Checkhov's rifle is a foreshadowing device. There is no requirement that the owner shoots themselves or that even any harm to the protagonist is caused. The protagonist can use it to kill the antagonist, the antagonist can use it against the protagonist, and anyone can even use it as a footgun. It's just a subset or extension of the "rule" "every scene should advance the story".
But a footgun is a very different thing and I think the miscommunication may be driven by this misunderstanding.
I’m speaking metaphorically. I know what footguns are, though I am using my words in a literary sense, and I think you’re being more literal maybe?
Implicit in the usage of the term footgun in a non-hypothetical context is that said footguns refer to actually existing issues or events. My point in mentioning Checkhov's rifle was to acknowledge this property of footguns: it’s not a matter of if but when they go off.
But seeing as how they will unless your process can eliminate them, it behooves us to apply some game theory to explain why collaborative development when footguns are involved is something between a Mexican standoff and Russian roulette: a circular firing squad.
We can’t blame the footguns at that point. That’s just the game. The only winning move is not to play.
I don’t mean literal guns, I mean literary[0] guns.
I feel that we agree, as I originally stated in my first reply, so I apologize if you feel that I’ve wasted your time.
My goal was to explain why I think that people leave jobs for higher pay instead of fixing things and getting promoted internally, which I believe was what you mentioned, which is party due to dysfunctional workplaces with footguns without proper safeguards, and in the context of this thread above you, people who have the context may have left the company, temporarily or otherwise, and those who remain to do the work may use LLMs to compensate.
[0]> (of language) associated with literary works or other formal writing; having a marked style intended to create a particular emotional effect: the script was too literary.
I'm saying a footgun is de facto metaphorical so it is a weird thing to accuse me of being literal. I understand Chekhov's rifle is a different thing, and a literally. I literally demonstrated knowledge of this. I literally stated as such
I don’t know what to say. I explained my position and you find it lacking. I make no accusations of lack of understanding, I merely lay out my reason for all to critique and correct, and so you may understand my thought process.
Do you think that metaphors can be used too literally? All models are wrong, and some are useful. Let’s not let the perfect allusion, that I didn’t make, be the enemy of the good comparison, that I didn’t (in your view), make. I’m fine discussing my views, but I can’t change what I said originally.
No one is finding fault with you in this thread, least of all me. If you persist in finding fault where I readily admit fault through deliberation, I might be led to believe perhaps you protest too much?
For me it is difficult to give good code comments just when code is written. The problem is solved, the tricky parts if any are internalized. I dont mind reading code so just documenting what the code is doing does seldom bring value. The important thing is to document why the code does things in an non obvious way and unintuitive scenarios and edge cases etc.
When revisiting code is the best time to add comments because then you will find out what is tricky and what is obvious.
Code reviews are also good for adding code comments. If the people reviewing are doing their job and are actually trying to understand the code then it is a good time to get feedback where to add comments.
There is a hack for that: write the comments before and/or as you write the code. When things are still unclear, weird.
Of course do a final pass on them to ensure that they are correct and useful in the end.
This is one example of document as-you-go, instead of doing it after "the work" is done. I find it generally leads to better outcomes. Doing documenting only at the end is in many ways the worst way to do it.
Here's my method, which is a bit similar to the siblings.
Your first "docs" are your initial sketch. The pieces of paper, whiteboard, or whatever you used to formulate your design. I then usually write code "3" times. The first is the hack time. If in a scripting language like python, test your functions in the interpreter, isolated. Then "write" 2 is bringing into the code, and it is a good idea to add comments here. You'll usually catch some small things here. Write the docstrings now, which is your 2nd docs and your first "official" ones. While writing those I usually realize some ways I can make my code better. If in a rush, I write these down inside the docstring with a "TODO". When not rushing I'll do my 3rd "write" and make those improvements (realistically this is usually doing some and leaving TODOs).
This isn't full documentation, but at least what I'd call "developer docs". The reason I do things this way is that it helps me stay in the flow state, but allows me to move relatively fast while minimizing tech debt. It is always best to write docs while everything is fresh in your mind. What's obvious today isn't always obvious tomorrow. Hell, it isn't always obvious after lunch! This method also helps remind me to keep my code flexible and containerize functions.
Then code reviews help you see other viewpoints and things you possibly missed. You can build a culture here where during review TODOs and other similar things can be added to internal docs so even if triaged the knowledge isn't completely lost.
Method isn't immutable though. You have to adapt to the situation at the time, but I think this is a good guideline. It probably sounds more cumbersome than it is, but I promise that second and third write are very cheap[0]. It just sounds like a lot because I'm mentioning every step[1]
[0] Even though I use vim, you can run code that's in the working file, like cells. So "write 2" kinda disappears, but you still have to do the cleanup here so that's "write 2"
[1] Flossing your teeth also sounds like a lot of work if you break it down into all subtasks 1) find floss, 2) reach for floss, 3) open floss container, ...
Sometimes I feel like watching people dig a hole until it starts filling with groundwater. They then start bailing the water out with buckets. They're very busy doing that, so the actual digging work slowly grinds to almost zero.
I stand at the edge of the pit, trying to talk to them about electrical pumps and drainage solutions and get yelled at: "I don't have time for your nonsense, can't you see I'm busy bailing water here!?"
It's a good visual story to describe something we all frequently do. We often create our own anxiety.
It's easy to hear "let's slow down a little" as "don't move fast" but it's wrong to interpret that because "slow down" is relative. There is such a thing as "too fast". You want to hear "slow down" just as much as you want you great calls to speed up. When you hear both you should be riding that line of fast but not too fast. It's also good to make sure you have a clear direction. No use in getting nowhere faster.
I'll use another visual analogy. Let's say you and I have a race around the world. I take off running, you move to the drawing board. I laugh as I'm miles ahead, and you go to your workshop, which is in the other direction. The news picks up our little race, and laughs at you as I have such a tremendous lead. I'm half way done, but you come out of your workshop having build a jet. I only get a few more miles before you win the race. The news then laughs at my stupidity and your cleverness, as if it was so obvious all along.
Sometimes to move fast you need to slow down. It takes lots of planning and strategizing to move at extraordinary speeds.
Yep. I feel like this every time a coworker pushes back on a code review “I’m just trying to get this to work”.
Okay but this is the ninth time in a row, and now you’re building on top of all the other half-baked bits, and the confusion from every one of these layering on top of one another is forcing you to do more hacks on hacks on hacks. And then when you finally “get it to work” there will be no way to disentangle this whole mess.
In some cases like clean written geometry algorithms the code _is_ the best technical documentation and attempts at verbal description would sound awkward and plausible become dated. In this case the purpose of the written docs is to offer enough context (possibly quite a lot) to understand the _why_ but the how is easiest to understand by reading the code.
I’m not arguing about your personal experience but these things are not absolutes.
The key thing is can a new developer jump in and understand the thing. Add enough docs until they facilitate this understanding as well as possible. Then stop documenting and point the reader to the code.
I disagree (a bit). It really depends on the person. I've know a good number of scientists who are great mathematicians but get confused as soon as they see code.
My point is that everyone is different. Documentation isn't just for developers and you never know who's going to contribute. It is also beneficial to have multiple formats just because even with a single person different ways make more sense on one day than the next. Having different vantage points is good to have. It is also good to practice your own mental flexibility[0]
I think the pytorch docs are a good example here. Check out the linalg module[1] (maybe skip the matrix properties section).
[0] This will also help you in the workplace to better communicate with others as well as makes you a better problem solver. Helps you better generalize ideas.
> most of these things can happen for poorly documented large codebase.
Documentation does not help beyond a point. Nobody reads the documentation repeatedly, which would be needed.
When you keep working on a project, and you need a new function, you would need to check or remember every single time that such a function already exists or might exist somewhere. You may have found it when you read the docs months ago, but since you had no need for that function at the time your brain just dismissed it and tossed that knowledge out.
For example, I had a well-documented utils/ folder with just a few useful modules, but they kept getting reimplemented by various programmers. I did not fault them, they would have had to remember every single time they needed some utility to first check that folder. All while keeping up that diligence forever, and while working on a number of projects. It is just too hard. Most of the time you would not find what you need, so most of the time that extra check would be a waste. Even the most diligent person would at some point reimplement something that already exists, no matter how well-documented it is. It's about that extra search step itself.
The closer you want 100% perfection you get exponentially increasing effort. So we have some duplication, not a big deal. Overall architectural quality is more important than squeezing out those last not really important few percent of perfection.
In my experience, the usefulness of documentation in code declines as familiarity with a codebase increases. The result: people ignore it; it becomes outdated; now it's debt. Similarly, non-intralinear documentation (documentation that isn't in the code) tends to grow with a codebase. Meanwhile, the codebase changes, personnel change, and more and more of the documentation beco.ed noise, a historical artifact of solving problems that either no longer exist or can no longer be solved the same way.
That being said, good documentation is worth its weight in gold and supports the overall health and quality of a codebase/project. Open-source projects that succeed often seem to have unusually strong, disciplined documentation practices. Maybe that's just a by-product of engineering discipline, but I don't think it is -- at least not entirely.
I'm sorry, but this is selling good engineers very short. If you didn't nest your utils folder 8 folders deep, it seems pretty obvious that one should check the utils folder before writing another utility function. This stuff should also be caught in code reviews. Maybe the new guy didn't know that util function existed, but surely you did when you reviewed their MR? Obviously mistakes like that can happen, but I've found that to be the exception rather than the rule, even in some of the gnarlier codebases I've worked in.
Assuming they even have code reviews - in your experience, in a situation where the person writing the code didn't check if it already exists, the reviewer will check that and then tell them to delete their already finished implementation and use that existing thing?
I wouldn't say you should explicitly check, necessarily. More like, you go to implement the widget and when you open the appropriate file to get started, it's already there.
I agree with you completely, but also posit that this is exactly what agentic LLMs should solve?
Claude code’s Plan mode kind of does this research before coding - but tbf the Search tool seemingly fails half the time with 0 results and it gets confused and then reimplements too…
I for one think that this discipline is what separates a good developer from being a good engineer. This kind of rigorous process is the kind of thing that I'd expect from most devs but is sadly missing most of the time.
New people contributing usually reinvent many things and change global configuration because they don't know they can use something already there.
Ironically indexing the codebase and ask LLM questions about specific things is the best thing you can do. Because the only 3 people who you can ask left the project or are busy and will reply within a week.