Why Documentation and Comments are Important in Code

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…