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.
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.
Be sure to include:
- 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!
Make sure to avoid:
- 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.