DEV Community

Discussion on: Don't document your code. Code your documentation.

Collapse
 
jillesvangurp profile image
Jilles van Gurp

Writing documentation is a pretty thankless job. Nobody will ever read what you write and no matter how much of it you write people will find something you did not document and complain about it. It's always somebody else that ought to document something. And somehow it is frequently implied that would be me.

So,my attitude to documentation is "by exception". Most code should be obvious and not in need of any documentation. But once in a while you do something non trivial and then it matters to document wtf. you were thinking. A simple link to a stackoverflow post to explain the totally non obvious workaround for some issue, the weird set of circumstances that caused you to add some null check or other condition that you chased down, etc. Those are the things that need documenting. All the rest is obvious.

I love little hints that outline the reasoning behind bits of non obvious hackery, algorithm choices, concurrency handling and other bits of code where somebody really went the extra effort to get things done the right way.