Thoughts on Code Documentation
Over the past few months, I’ve worked on a rather big project: the Ozon.ru, one of Russia’s leading online stores, iOS app. What’s even more important than its size is the fact that the app is constantly evolving-both on the inside and the outside. With hundreds of commits added to the trunk branch weekly, one has to read and understand a lot of others’ code to stay current on the latest changes.
One of my key takeouts from working on the project is the notion of code documentation’s importance in the process of software development.
First of all, it’s worth outlining what code documentation is and what it’s not. By code documentation I don’t mean a couple of comments sparsely added to the most difficult-to-comprehend expressions. I prefer to see documentation as a routine thing that supplements every piece of code, especially those exposed to an outside scope (i.e. used beyond the current class). It’s something like what you can find in Apple’s own frameworks.
For the purposes of this post, I define three degrees of documentation quality and completeness: okay, good, and great.
Originally published at https://swift.ym.dev.