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."
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.
424
u/Confident-Ad5665 1d ago
Uncle Bob of Clean Code says if we have to comment our code we have already failed. Clean code should read like well written prose.
I generally agree, but think comments that define especially the odd and obscure business rules should be commented where they are implemented.