Recently I have been considering how to best add documentation to your code. This came up recently when I was helping someone work through a method and understand the results returned. I found that some comments and documentation were useless whilst others were not. As we worked I realized that the best piece of advice I could give would be to give it to somebody else. Here I have put together a quick guide on how to effectively add documentation to your code.
Documentation before your methods.
It is always wise to have a comment before your methods to give a quick explanation of there use. The comment should explain the methods exact use in simple terms without getting too caught up in exact details. These comments include…
- The parameters and any limits on these parameters.
- The returned value, if there are bounds to the returned result and any error values that may be returned.
- Any exceptions that this method may throw and maybe reason the exception may be thrown.
As we are writing in java these comments can be include html within the comment and block tags so we can use javaDoc to generate detailed API documentation. More details on this can be found here.
Documentation during your methods
If you have done the above then you have some documentation so that it will be easier for others to use your methods. Now we want the method to be easier to maintain. For this reason we should add more specific comments within the actual method. These comments should have one of the following purposes…
- They should describe the use of a variable or group of variables being defined.
- They should divide up the method into distinct sections so that each part of the method has its function explained. These comments should explain the code in general.
- Complex or overly technical sections should have additional comments explaining the section in greater detail so that the code can be followed more clearly.
Ideally these comments within the method should be understandable to someone new to the code and even to yourself should the code be left untouched for sometime before you need to make modifications to it.
Documentation after your methods
Now you should have a method that looks well documented making the code easier to understand. Now is time for the last idea that I find to be the best so far. Give the code to somebody else.
So far you have written some code, a method, a class or maybe an entire project. You have it well documented, assuming you are already familiar with the code. The next question is how effective will the documentation be for someone who hasn’t written the code themselves. If you don’t have to look at the code for some time will you understand the documentation fully yourself.
My advice would be to find someone else who is willing to look through the code and attempt to understand. As they work through the code…
- If they understand the code on the first time reading the comment, then that comment should remain unchanged.
- If they understand the code after reading the comment several times or have to spend time working out the codes function they should attempt to reword the comment in order to make it clearer working with the original author.
- If they are unable to grasp the comment and codes meaning they should go back to the author, ask for clarification and try rewriting the comment working with the original author to find a better wording for the comment.
After you have have finished the above three ideas you should have code that is easily understandable before people of all level, from those who are just making calls to a library to those who will be modifying your software or developing it further.
Feel free to share your own experiences and what you have found to be the best ways to create easy to understand documentation in the comments below.