Why documentation is more important than code

Taking a break from the machine learning heavy posts, I would like to talk about something slightly different but very important: documentation. Which is more important: code or documentation? If asked, most developers would say that code is more important than documentation. As a developer, you are given some business requirements and are asked to deliver a solution. That solution is your code. It works and solves the problem. Done!

There is nothing wrong with this argument. At the end of the day, code gets the job done. And if you’re on a tight schedule such as trying to fix a production issue then yes, your code is way more important. But that’s not the scenario I am talking about. I am talking about most of the development that gets done where developers are given sufficient amount of time. That’s when you must document your code. Whether that be through comments or separately on a wiki page, it is your responsibility as a developer to add that additional information for your team.

Why document?

Code is an outcome of all the decisions you made to meet the business requirements. As with most business requirements, there are multiple ways to implement them and what you end up coding is a reflection of all the decisions you made after considering all the factors and limitations. If you give the same business requirements to a different developer a year later, they might have a completely different implementation. Hence, it’s critical to annotate your work with more information to help your team understand not just what you are doing (that’s easy) but why you are doing it that specific way. Why is it that you decided to hardcode a certain threshold for a data quality check, and why is it that you chose to use perl to write your script rather than python? The answers to these questions might be completely valid especially when you consider that the code was written by someone else at a different time when priorities and/or requirements might have been different. However, as a developer, it is your responsibility to document that information.

This brings me to my next point and something that is engraved in my brain by my ex-boss. He once told me (and I am paraphrasing): “Make sure to always write code, not for yourself, but for the next developer who will be working on it in future.” This is very important and I wish this was enforced in every company. Your code is not something that lives in isolation. It’s part of the main source code and will eventually be worked on by someone else sooner or later. It is your job to make sure that developer doesn’t have to spend hours just trying to figure out why you did something in a particular way.

How should you document?

There are different ways to document and each team has it’s own way that works best for them so I don’t want you to think that what I am about to tell you is the way of documenting. It’s just the way that I follow. Feel free to leave comments if you know of better ways.

I document in three steps:

This fact is attributed to the long lasting effect that is the effect of the medicine is available in tablet form and obtainable in three different dosages- 25mg, 50mg and 100mg. viagra sales uksare manufactured by Pfizer pharmaceuticals and supplied in all over the world. You are not complete generic cialis no prescription deeprootsmag.org without a partner, this is the law of nature. If you happen to frustrated as well as nervous regarding your love-making abilities you possibly will not want sex and have the identical price viagra medical effect. They also get misunderstanding that their males are having extra best viagra online marital affairs.
1. In-process: I always create a wiki page to document as I am working on a task or project. I document the problem statement, ticket number that corresponds to this task, proposed solution that I think works best and many other things that I just want to track as I work on this task. It’s semi-formal and is mostly used by me while I am working but it can also provide my team with insight into how I developed the final solution.
2. Annotations: Your code should have A LOT of comments. Some people might argue that you should only document stuff that’s not obvious but that is quite subjective. What’s obvious to a developer with 30 years of experience is not so obvious to someone who just graduated from college. My rule of thumb is that it’s always better to add more comments than less. Take a look at this code I wrote recently and notice how many lines of comments I have.
3. Final documentation: Given the size of the task, your final code might look very different from what you originally imagined. Requirements might have changed or you might have gotten good feedback from your team. Whatever the case might be, you want to have a proper formal documentation on a wiki page that is detailed and describes the final state of your code. This will be the page that your dev and support team will look at for a long time so make sure it’s good!

Some people might argue that it’s always better to document the code directly than to create a separate wiki page because they tend to get outdated quickly. That’s true, wiki pages do get out-of-date quickly but they are still better than nothing. Not everyone in your company will have access to your code so it’s important to have some documentation available public on an internal platform.

Changing the culture

If you are a manager, you might be nodding your head but are probably wondering how can you efficiently implement this culture in your team. How do you convince your team of developers to pay equal, if not more, importance to documentation?

First of all, documentation is a habit. It is not developed overnight but once you are comfortable documenting as part of your routine, you won’t give up. It will be tightly integrated with your ‘coding process’. Developers will not close their ticket unless their code is properly documented.

Secondly, you have to make sure to properly enforce it. By that I don’t mean to be too strict or start micromanaging your developers but start asking them whether the documentation is ready before you close any of their tickets during a sprint meeting. Make sure to bring it up every time casually and slowly, you will see that it will become part of your team’s culture. Refuse to accept any code change without a proper documentation. It might be slightly annoying at first but will be very beneficial to the team and the company in the long run.

Overall, I would like to appeal to developers who think that documentation is a waste of their time which can be better utilized by either improving existing code or writing new code. In the long run, it will make your life much easier. You will not have new joiners bothering you with questions about your code since they can easily get answers from your documentation. Also, you are not working alone. You are part of a team and it’s your responsibility to make sure that others can easily understand your code. And keep in mind, if everyone in your team documents, that means you also save time when you have to work on some code that an ex-colleague wrote 3 years ago!