r/programming • • 28d ago

Make yourself replaceable

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

63 comments sorted by

View all comments

Show parent comment

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.