I actually agree that “good enough” code can be self-documenting, but it isn’t always enough to achieve my goal which is to make the code understandable to my audience with minimal effort. With that goal in mind, I write my code as I would write a technical document. Consider the audience, linear prose, logical order, carefully selected words, things like that… In general, I treat comments as a sort of footnote, to provide additional context where helpful.
There are limits to self-documenting code, and interfaces are a good example. With interfaces, I use comments liberally because so many of the important details about the implementation are not obvious from the code: exactly how the implementation should behave, expected inputs and outputs under different scenarios, assumptions, semantic meaning, etc. Without this information, an implementation cannot be tested or verified.
I actually agree that “good enough” code can be self-documenting, but it isn’t always enough to achieve my goal which is to make the code understandable to my audience with minimal effort. With that goal in mind, I write my code as I would write a technical document. Consider the audience, linear prose, logical order, carefully selected words, things like that… In general, I treat comments as a sort of footnote, to provide additional context where helpful.
There are limits to self-documenting code, and interfaces are a good example. With interfaces, I use comments liberally because so many of the important details about the implementation are not obvious from the code: exactly how the implementation should behave, expected inputs and outputs under different scenarios, assumptions, semantic meaning, etc. Without this information, an implementation cannot be tested or verified.