Quality Code: Documentation
Quality Code: Documentation!
See the header image of this post above? The one we use to represent "code?" That is an example of very difficult to maintain code! No documentation, and no formatting. It’s a complete mess for a human to understand. That being said - we do the same for code that lives on our production servers. We compress the data and strip out all our documentation before pushing code live. If this is what your code always looks like (for example when you work on it, instead of when it is live) - you might want to spend a weekend or two untangling that mess. I’m going to skip the formatting issue and focus on the documentation side of things.
Documentation as a Starting Point
Even messy code is better with documentation. It explains intention, and conveys meaning (useful when the code doesn’t.) Documentation is the accounting part of developing software applications. As we all know, accounting is the only thing more exciting than computer programming. Creating and updating documentation is a great way to start small, and have an impact without even changing how the code works! If you don’t use versioning, you could put something like “this was last updated in November." Useful already! From there, it makes you ask questions like “what does this do?" which will give you a more complete understanding of the system.
The Mindset of Documenting Code
Speaking of understanding, documentation puts you in a much better mindset to write code. Once you start writing documentation you start to think about other people reading your code and documentation. Writing code with the rest of your team in mind is a great perspective on your way to creating maintainable tools. Your tools will be more readable when complemented with supporting documentation. You will also be less likely to cut corners if your peers are trying to understand what you’re trying to say.
Semantic Documentation
Documentation should carry meaning. If you find yourself writing documentation in different formats and styles...then there is a good place to start thinking in common, reusable patterns. It turns out writing documentation is great practice for writing code. Organizing ideas and presenting meaning in a clear fashion is a valuable skill in both domains. Documentation should have value. In my books, great documentation allows you to gain a better understanding of the system without even looking at the code.
Quality Documentation and Quality Code
As software developers with deadlines and bugfixes we only have so much we can understand in a single day. Quality documentation allows us to find what we are looking for more quickly, without having to digest as much code. Even great code has a cognitive cost associated with reading and understanding it. The more we can reduce that cost - the more productive we can be! How is that for a sell to management? Better documentation leads to more productivity, which is a bonus for anyone (and hopefully a cash bonus, too.)
Tap or click on these posts to navigate to the next or previous posts.
This post is part of a larger series. Tap or click on a post to view more in this series.
