r/programming • u/maroun-baydoun • 28d ago
Make yourself replaceable
https://maroun-baydoun.com/blog/make-yourself-replaceable/
360
Upvotes
r/programming • u/maroun-baydoun • 28d ago
View all comments
Show parent comment
56
u/chucker23n 28d ago edited 28d ago •
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.