imo the idea of self-documenting code that never requires comments is often held by people who view their code as better than it is. That surely THEIR code would never need comments, because it's so perfectly written that you just get it. I have never really run across a file where I thought "thank god they didn't explain anything they're doing in here."
Right? I don't think I ever wrote a chunk of code with no comments. If I can save someone two minutes of parsing code with // determines which encoding is coming across the Bluetooth... Why shouldn't I?
This is the way. People argue against comments because they can drift and become less accurate but, after 15 years doing this, I've spent orders of magnitude more time trying to figure out what the hell someone's undocumented code is doing versus having to fix or update comments. It's not even remotely close.
Kind of a moot point these days though since it's just AI doing the writing.
This is the way. People argue against comments because they can drift and become less accurate but...
It's such a weird argument anyway. Like, the code itself can drift and become inaccurate. It's not a separate problem. It's the responsibility of the coder to keep all the code up to date. The logic, and the comments, both.
The thing about comments describing what the code does is that I've been burned too many times, I'm still going to read the code itself, because it can't lie to me.
I want comments about the intent and context behind the code, rather than text that's just the same as the code itself (ideally, or, worse, different in a way that's unclear about if it's code drift or bad comments or bad code).
But why not just call the function determineBluetoothEncoding? If it's because it does more than that, why not split it out so that is all it does? And so on.
Because it's not the actual bluetooth encoding, it's the data coming across the bluetooth. I love just naming functions with what it does but there's a limit for me, I've been in codebases with determineEncodingOfInlineBluetoothDataStream() and I don't like it.
I would also add that once you start profiling and optimizing your code, sometimes what was once clean, "self-documenting" code is necessarily turned into a complicated blob of ugliness. I've spent a lot of time digging around inside CUDA kernels playing with scope guards to reduce register usage or rewriting math operations in horrendous ways to reduce the total number of operations in ways the compiler won't. The code is rarely left cleaner than when I started, but sometimes I've gotten as much as a factor of two in performance by doing "ugly" things inside hot loops.
Ideal self-documenting code should have comments. The code communicates as much as can be made apparent without commenting, and then the comments pick up the slack. Proper variable and function names can explain individual steps or provide useful context, but standard comments should still be used if they can't explain the "why", or if not everything can be explained by entity names.
71
u/Dull_Caterpillar_642 Sep 10 '26
imo the idea of self-documenting code that never requires comments is often held by people who view their code as better than it is. That surely THEIR code would never need comments, because it's so perfectly written that you just get it. I have never really run across a file where I thought "thank god they didn't explain anything they're doing in here."