DEV Community

Discussion on: Self Documenting code isn't

Collapse
 
napicella profile image
Nicola Apicella

There is no silver bullet and it's matter of trade offs like everything else, but generally speaking I think we should strive to write self documenting code.
Besides the obvious advantage of keeping in sync code and docs, self documenting code usually means code which is more modular, testable and reusable.

There are exceptions, for example like you mentioned, comments which explains the why some code does what it does.

There might be cases in which you also need do write comments to explain what the code does, but I really see it as an edge case, as a last resort.

One of those cases is when you write code which deals with microseconds latency. If I realize that adding a new class or new functions would cause a regression, then as a last resort I would write a comment.