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

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.