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.