3 ms·
You can still document the why in commit messages![1] I feel like I’m getting off the self-documenting code ride. In our own codebase we rely way too much on “
by keybored 2y ago
You can still document the why in commit messages![1]
I feel like I’m getting off the self-documenting code ride. In our own codebase we rely way too much on “descriptive names”. Like full-on sentence-names. And is the code self-documenting? Often not. You indeed cannot describe three or more axes of concerns in one name.
Do comments go stale? Well why does it? Too loose code reviews? Pull requests that have fifty lines of diff noise that you glaze over? We have the tools to do better on that front than some years ago at least.
It’s a joy to find a corner of the code base where things are documented with regular sentences. Compared to having to puzzle through five function call layers.
[1] But yeah, really. But also: sometimes also in comments. Sometimes both.
- klingoff 2y agoRight, commit messages are at least always right for the context that comes with them. I think long descriptive names are an anti pattern. As per word puzzles you can't actually read the middle of a blob of text so you are basically left with a dozen variables that are cognitively the same as isDatabaseHidingDragonsSetter().
- oxidant 2y agoI mostly like a comment with a succinct explanation and a longer commit message. Comments are less likely to be refactored and lose the immediate git blame, while the function might change over time. Ideally the future user would trace the git blame back to the original commit of they really had questions. A long comment is really helpful sometimes though. I like to put ascii truth tables for complex boolean logic, both to ensure I cover all cases when writing the code (tests, too) and to make it easier for future me to understand what's going on at a glance.