![](/static/253f0d9b/assets/icons/icon-96x96.png)
![](https://programming.dev/pictrs/image/170721ad-9010-470f-a4a4-ead95f51f13b.png)
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.
An autistic coder would have documented this feature to the point of pedantry.