The idea behind self-documenting code is that much documentation that would normally be required because the code is so poorly written, becomes unnecessary if t

The idea behind self-documenting code is that much documentation that would normally be required because the code is so poorly written, becomes unnecessary if the code was rewritten to more clearly express what it’s doing. It is absolutely true that code cannot be fully self-documenting, and the idea of writing self-documenting code isn’t to suggest that it can be. E.g., why things were done a certain way is not readily expressible through code. And it’s often helpful to give a plain-language overview of the purpose and responsibility of a class, for example. In my experience, writing as “self-documenting” code as possible is vastly preferable to a culture which cares more about writing comments for everything than writing readable code. People end up writing obligatory but worthless comments; comments are strewn everywhere making it even harder to read or skim code; and you end up getting vastly more comment rot.