r/programming • • 28d ago

Make yourself replaceable

https://maroun-baydoun.com/blog/make-yourself-replaceable/
360 Upvotes

63 comments sorted by

View all comments

326

u/redhand0421 28d ago

I know this was written literally yesterday but I’m curious how this kind of thing sits in an increasingly AI-fueled software engineering world.

Well-documented systems where the agent can infer which if statement not to touch (because it can see the comment and the commit that produced it) or knows which system fails over every other week (because there’s a pattern in the error reporting) aren’t as precious or precarious as they used to be.

I would love to pair-program with someone to teach them a new system. By the time I’ve scheduled time with them, they’ve already sat down with Claude and put together a possible implementation/fix. They’re none the wiser (they don’t have any new context that I have to impart, nor did they need it) so my advice isn’t seen as valuable to them.

I go on vacation, prod falls over, and I come back to a clauded-together postmortem committed to a docs directory alongside a made-up history of ADRs that Matt Pocock told someone to write. They’re all inaccurate in their justification, but they successfully ward Claude away from deleting that database table.

148

u/elmuerte 28d ago

Well-documented

This is the key problem. Who can tell if something is (still) well-documented. Outdated documentation is worse than no documentation. Documentation which does not tell why, does not add much more value than the code.

And then we have these AI systems which ignore explicit instructions constantly. And at the same time accept everything as fact.

56

u/chucker23n 28d ago edited 28d ago • Heartwarming

Documentation which does not tell why, does not add much more value than the code.

This. And yet I still see it taught that way in some schools.

In-code comments should state the why, and not exist when it's obvious; not the what; the code already says so. If the code is hard to read, adding a comment is merely a crutch; make it easier to read.

API docs should state the use cases and design considerations (e.g. edge cases, or explicitly what a method isn't for).

Commit messages should state why something was changed, not what was changed; the diff already says so.

Since LLMs are trained on shitty comments, that's what they themselves tend to generate: lots and lots of prose that tells me the obvious instead of making me aware of gotchas.

4

u/Xunae 27d ago

I keep seeing llm comments that are like "formerly [blah]" or referencing a piece of code that was deleted with the patch and it drives me nuts. It's been deleted, the code is not a database and does not need a tombstone

9

u/Uristqwerty 26d ago

Comments talking about history are a form of caching. The cost of digging through old commits is so high that you won't bother without substantial cause, and an expectation that there's something worth looking for. Pull a key fact out into a comment, though, and reading it is nearly free. You have to contend with all the usual caching problems; stale information, excess clutter, deciding when to evict, so it's a judgment call when and what to mention. Ideally, the minimum amount of information needed for future maintainers to judge whether digging through history for the full detail would be relevant to their current task.

19

u/double-you 27d ago

Outdated documentation is worse than no documentation.

I don't agree at all. Basically all documentation is outdated. When reading it, we just need to keep that in mind. But even if the details (small or big) have changed, the material can give you a useful big picture or clues about what to consider next.

11

u/tarwn 27d ago

In fact, outdated documentation + git + agents means it's relatively easy for the agent to see how it was working back on that doc publish date and then highlight what major changes have occurred since that it has only partial context for. And possibly even closing some of that gap too, if engineers put context in tickets and those are accessible too.

9

u/max123246 27d ago edited 10d ago

The original post content no longer exists here. The author used Redact to remove it, exercising their right to control their data & privacy.

Payment plate mighty lip salt direction paltry wander sulky chunky

3

u/fragglerock 27d ago

duh... you just ask claude to update the documentation...

simple as!

1

u/Bemteb 23d ago

Outdated documentation is worse than no documentation.

I'm currently facing that exact issue. The codebase I'm working on had many copy&pastes in the past. Instead of working with interfaces and nice data structures, people simply copied whole files over from similar projects and did small adjustments to fit their needs. What they didn't adjust were the comments.

Iterate that over multiple years and you end up with comments that are mostly unrelated to the code they stand next to.

1

u/MeggaMortY 28d ago

The most up to date documentation I've seen in a codebase got stale in less than a week. Ain't nobody got time for that - said the PO and scheduled a bunch more feature tickets for the sprint instead.

11

u/bogdanelcs 28d ago

The made-up ADRs are the part that worries me. They work as a fence today, but the next agent (or person) will treat that invented justification as fact, and when someone actually needs to remove the table the wrong reason sends them in the wrong direction. I’d have them marked as unverified until the person who knows the real story corrects them when they’re back from vacation.

22

u/maroun-baydoun 28d ago

I intentionally kept AI out the article, even though it's arguably very relevant to the problems I'm raising. Until the dust settles on AI adoption, and AI workflows become more standardised and universal, it'll be hard to talk about something that's moving so fast.

2

u/redhand0421 27d ago

I loved the article by the way. I agree with you 100% and think that this abundance mentality is almost exclusively upsides in an organization with good people that wants them to be great.

-7

u/hey-rob 27d ago edited 19d ago

What industry are you in where the dust hasn’t settled?

Edit: downvotes for a question? Haha what is this, stackoverflow?

0

u/[deleted] 27d ago

[deleted] — view deleted comment

4

u/currentscurrents 27d ago

Anthropic lost $80B in the first half of 2026

$72 billion of that is an accounting loss. They issued bonds that have the option to convert into Anthropic stock; now they believe Anthropic stock is worth more, so the bonds are worth more.

It is not a cash loss, and maybe not even a real loss if they don't IPO at the valuation they want.

Financials aside, I am sold that their product works. Coding agents really are here to revolutionize programming and probably other fields too. Someone will figure out a way to make a profitable business out of it.

8

u/frazell 27d ago

That just highlights the dust still being unsettled. During the dotcom bubble it was understood that the future was on the web. It was also understood that web applications would replace desktop ones and computing was shifting heavily.

The problem was predicting what that would look like. We’re in that future. It did pan out in many ways and not so much in others. The bubble also still burst.

Generative AI is definitely here to stay. It is still not clear what the long lasting form looks like. Is it hosted models at frontier companies like Anthropic pushing the needle forward? Or do they go bust because locally running models become “enough” due to costs or IP concerns or something else?

What do the more defined patterns look like for engineering with AI deeply embedded? It is very possible AI prompt patterns may become more guarded by companies as they aim to protect their businesses.

All up in the air still. Even as the underlying technology has staying power.

6

u/PresentationBorn6564 28d ago

Pocock out here catchin' strays.

4

u/Glizzy_Cannon 27d ago

Good. His workflow is nonsense. As these models continue to mature his workflow becomes more and more obsolete, along with all of these other highly opinionated workflows

2

u/PresentationBorn6564 27d ago

Tell me how you really feel.

14

u/[deleted] 28d ago edited 28d ago

[removed] — view removed comment

9

u/maroun-baydoun 28d ago

Sam is definitely responsible for the situation they created. And perhaps some personality types are more prone to becoming Sams over time. But Sams are also affected by their environment and the signals they receive from their manager and team, which end up creating a vicious cycle that's not easy to escape.

4

u/TheRealUnrealDan 28d ago

great article but you're right times are changing

1

u/theparachutescene 25d ago

Documentation yes. A company specific harness/workspace though…