I know when you're vibe coding

I think size of the code base matters a lot too. In a multi-100k line of code application, you might not know a utility function is already defined somewhere and reinvent the wheel.

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.

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, ...

  > 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]

[0] https://news.ycombinator.com/item?id=44744167

> 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 someone somewhere, 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?

https://en.wikipedia.org/wiki/Chekhov's_gun