Why Documentation and Comments are Important in Code

Brian Yee
Brian Yee
Jul 19, 2019 · 3 min read

When you are writing code, you are writing for three main audiences: the users, other developers, and yourself. Your code should be easy to understand and use, otherwise anyone trying to use your code might start looking for better alternatives. The first step to making sure your code is easy to understand is documentation.

So what is documentation and how is it going to help? Documentation is the manual that explains what a function does; this is usually done by describing the arguments that the function expects and what the function returns. This can give a quick refresher on what a function does if you are looking back on code from months ago. Without this, users could waste a lot of time trying to figure out what the function does.

Imagine trying to figure out all this without documentation.

Without documentation the user would have to fumble around with the function, get thrown errors, adjust their use of the function and repeat this process until they finally get the function to work. This might be fine with simpler functions, but when functions start getting more complex, this process of trial and error might never end. With proper documentation, the user can simply use the help() function and get all the information they need about the function right away.

Now what if you have code that other developers will be collaborating on? Documentation will be nice to understand the function at a higher level, but developers will care more about how the function actually works. Comments will help developers follow along with the code and give insight into the thought process of the original author. Comments also allow collaborators to communicate to each other which parts of the code need to be worked on or possible improvements that could be made.

Even if you write code that you don’t intend to share with others, documentation and comments can still help you in the future. Sometimes you will have to look back at code that you have written months ago and concepts that might have been clear for you back then might have gotten lost as you worked on other projects in between.

Well written documentation and comments can be helpful, but if written poorly they can be useless or even harmful to the clarity of your code. Here is a list of things to include and avoid when writing your own documentation and comments.

  • what the function does.
  • what arguments the function expects.
  • any known issues with the code.
  • up-to-date information.
    Information about code that has since been changed is of no use to anyone.
  • credit where credit is due.
    Make sure to credit anyone who contributed to the code!
  • unnecessary information.
    Don’t include anything not related to the code and avoid over explaining.
  • assuming the user’s knowledge.
    The documentation needs to be helpful to everyone, from experts to beginners.
  • confusing formatting.
    Doesn’t matter how much information is in the documentation if no one can read it.
  • ambiguous or hard to understand language.
    Documentation has been standardized to be written in English, so it is going to be used by non-native speakers of English as well.

The Startup

Get smarter at building your thing. Join The Startup’s +724K followers.

Brian Yee

Written by

Brian Yee

Data Scientist from Flatiron School NYC

The Startup

Get smarter at building your thing. Follow to join The Startup’s +8 million monthly readers & +724K followers.

Brian Yee

Written by

Brian Yee

Data Scientist from Flatiron School NYC

The Startup

Get smarter at building your thing. Follow to join The Startup’s +8 million monthly readers & +724K followers.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store