Every Software Developer Hates It
Documentation can be the greatest thing ever. It can help us to work together and create great software. That’s not what any developer has ever said, ever. So let’s delve into the reasons The Secret Developer likes documentation and does not mind spending time at work away from coding.
Why The Secret Developer Likes Documentation
The Secret Developer usually likes to spend 110% of their time coding and solving problems. So it might be seen as a surprise that they are willing to spend time helping others to understand their code.
“While I like documentation I think it should be used in moderation. Using comments to document what code does instead of why is an anti-pattern in my book. Yet good documentation with quality naming can give us opportunities to create great code as a team.
I’m not simply saying this. There are reams of evidence for thinking about documentation when creating great software.”
The Evidence
There is evidence that documentation is important. Yet it says more than that, so let us dive in.
“Results showed that developers were able to reliably comprehend the function of an application which was written with the aid of a framework that used a descriptive interface naming style and was accompanied by interface documentation”
naming style + descriptive interface + documentation = developers who understand
“For me, this is all about standards. It’s not just about documentation but it’s about powerful naming that conforms to a style. Having one without the other might be useful, but it is not as useful as having both together.
This is what we should be aiming for when documenting code. We should always be aiming higher, and thinking about documentation will help us to do so.”
Yet More Documentation
“Yet documenting seldom-used processes can be a real boon for developers and save so much time.
We can crystalize and agree on processes while having something concrete to refer to. This record of agreements can persist even when colleagues change over time. That’s good in a place like mine where we have a high turnover of staff.
We can also record practices to help with onboarding and even things like performance expectations for employees. This all saves time and we have a document we can agree on and make concrete.”
Conclusion
Documentation should be about making life better for others. Being considerate and adding to the quality and maintainability of carefully crafted code.
“When I haven’t documented properly my future self has got amazingly angry at me.
Take that as you will.”