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:

  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!

4 responses to “Why documentation is more important than code”

  1. Ritvik says:

    I only partially agree with this. Yes, you should write code for the next developer to easily understand your code and it should be readable, but over commenting the code has a lot of downsides. The major one being keeping the further code changes consistent with the comments. Comments are a maintenance overhead. In a perfect world comments would be changed accordingly when the code is changed. But we know that doesn’t happen too often. So as the “Pragmatic Programmer” says, I’m a proponent of self-documenting code in most cases. I only like to comment on API methods to mention the task of the methods and the constraints. I think it’s important to not overly document the code since by trying to help the next person working on the code you might be adding overhead on their work to maintain the comments (if they even care to fix them as they change the code). Thoughts?

    • Himanshu says:

      I completely agree. Like with everything else, there is a limit to how far you should go to implement it. I have seen code with every single line being commented on which is an overkill. It’s better to stick to higher level commenting – why something was done a certain way etc.

      And yes, outdated comments are not fun so it’s up to the next developer to make sure when code is changed, comments also change accordingly.

      This reminds me that I still need to read that book!

  2. Varun says:

    Nice Article! I would like to add that documentation is definitely a skill as well since there are issues with just throwing comments in code. For example – Developer A writes all these comments, then makes some fix which changes the nature of the code but forgets to updates the comments which makes the documentation useless.

    I also think certain languages need the extra documentation vs. others. For example, Java being so verbose doesn’t require a ton of comments but other languages specially functional languages definitely require the extra bit of info for understanding the flow.

    I would definitely recommend reading clean code – {chapter 4 – Comments} which goes in-depth on some best practices for comments and pitfalls of over commenting.

    • Himanshu says:

      I agree and Ritvik (see comment above) also touched on the same point. It’s definitely a skill that takes time to develop. Also, it’s the next developer’s responsibility to make sure when they update the code, they update the comments as well. Whether you write the comments in code or document on wiki, you will need to actively keep them updated. But outdated documentation is still better than not having any documentation (in this context).

      Thanks for the recommendation. I will check out the book!

Leave a Reply

Your email address will not be published. Required fields are marked *