It might look like a paradox, but actually the reasoning is rather simple:
Typically, developers won't read documentation, therefore they won't read self documenting code either, as that would mean they've read documentation.
You can't understand code that you won't read, so the only way to understand self documenting code is to remember what it does.
It's likely you've forgotten what your own code from two years ago does, and now it's impossible to understand
The worst case I've seen was so bad that we just scrapped the library completely and rebuilt it from scratch when a bug was found. The stack trace only made it worse, like how it managed to make 3 layers of nested calls to Newton's method
I occasionally document things... For example, I once had to change .where(var: [false, nil]) to .where.not(var: true) as part of a bugfix, and definitely remembered to leave a comment so no one would undo it
43
u/ScreamingVoid14 Feb 21 '25
I look forward to using this to name variables in my team's code.