How to best add documentation to your code

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.

If you’re a first-time reader, or simply want to be notified when we post new articles and updates, you can keep up to date by social media (TwitterFacebook and Google+) or the Blog RSS.

Ebook Page Link

The following two tabs change content below.
Kieran France is a programmer for IDRSolutions. He enjoys tinkering with most things including gadgets, code and electronics. He often has no idea what to write in his blog posts but tries his hardest to make them interesting and entertaining, he also makes no excuses for his odd sense of humor.

Related Posts:

KieranF

About Kieran France

Kieran France is a programmer for IDRSolutions. He enjoys tinkering with most things including gadgets, code and electronics. He often has no idea what to write in his blog posts but tries his hardest to make them interesting and entertaining, he also makes no excuses for his odd sense of humor.

3 thoughts on “How to best add documentation to your code

  1. Todd Runstein

    I respectfully disagree with the bulk of your post. It likely just needs some qualification, but generally, in my opinion, the best comment is the one you don’t write. Documenting a public API is one thing, but it was troublesome to “work through a method and understand the results returned”, the problem was not lack of comments, but poor coding and lack of unit tests.

    Unit tests should allow you see how the method works . . . once reading that, there should be no question about how to use the method or what it returns. And if the code is written well, you should be able to understand it easily.

    I especially disagree with your “Documentation during your methods”. If you have to “describe the use of a variable or group of variables being defined” in a comment, you’re not naming it well at all. If you need to “divide up the method into distinct sections”, the method is doing too much and should be refactored into smaller, easily understandable methods.

    I realize you may see this as a flame, and that is not my intent! I understand your desire to have code be understandable. Believe me, I’ve seen a lot of code that’s so bad it makes your head hurt. But, I’ve also read heavily commented code where the comments get stale and therefore become more confusing than helpful. Instead, I like to work with code that clearly expresses it’s intent. One of the best descriptions of this, again in my humble opinion, is Uncle Bob’s book “Clean Code”.

    Again, I hope you don’t see this as argumentative! I wouldn’t blame you if you thought I was just some asshole on the internet who likes to argue. Again, that’s not my intent at all!

    Sincerely,

    Todd

    • I actually agree with you that clearly written code should not need documentation and I am really quite bad at wording blog articles so I thought I would add some explanation.

      The main thoughts in my article were based on two things I have noticed.

      The first is that although we can look at the code and see how it works it does not necessarily explain the why. For instance in my case I think I can safely assume there are large numbers of developers that use 3rd party libraries to support pdf that do not know the pdf spec in depth. Comments explaining the function / use in relation to the spec can and have proved useful in the past.

      The second is related to the first. I have found we will get support questions from people attempting to use or modify the code, many of these questions can easily be answered by looking at the pdf spec if you know where to look. Adding comments is just another way of getting support to those using the library as hopefully the questions are answered without having to contact support and wait for a reply.

      It can be a time saver for the users and the support team as every new user that wishes to modify the code effectively starts as a new member of our team would start, having not used the library before, but without the rest of the team there to teach them the ins and outs of the library. I believe different coding styles and different applications require different approaches, I personally feel that for 3rd party libraries more explanation of the why of the code helps with understanding the library and it helps when trying to interact with or modify the library. But again this is just my opinion.

      I have seen articles online preaching that if you have added any comments to your code then you have failed to code effectively and I’m sure that is not what you’re saying. Reading my article this morning it does sound like the intention was to add comments everywhere and throw common sense out of the window, but that was not the intention. Only add documentation where it is needed, then use this approach, where it it needed.

      All things in moderation, including documentation.

      (Oh and I have ordered a copy of Clean Code as it sounds like it has some good ideas, once I have finished it I will write an article reviewing the book and the ideas within. It will be interesting to see how my opinions on comments change)

  2. Danny

    In my own experiences as something of a “documentation evangelist”, I find software developers in general have a “code is done, so on to the next ticket” mentality. When you start holding them to task, they can be made to write unit tests. After that, I can get them to write documentation. So it tends to be a “pick your battles” type scenario.

    The compromise I’ve made that seems to work well is this: I’ll let your lack of documentation slide if you only document your interfaces. I will figure out your implementation by writing tests or pouring through code or manually testing, but worst case scenario, if the interface is documented and well-defined, it is possible for me to flat out replace an implementation I don’t understand with one I do.

    With that in mind, I agree with most of this post and what makes good documentation. One of the biggest problems I find is with not documenting edge cases. This typically entails things like “what happens if this method does not return successfully”, or “can this return null” (for java devs) and “can implementations reasonably expect the arguments to be non-null”?

    Lastly (and again, chiefly for Java), the rise of non-operational annotations has been very helpful for allowing some useful documentation with little overhead. For example, sprinkling @Immutable on top of a class or @NonNull to a return type or argument allows a developer to provide a lot of information about how the class or method should be interacted with with minimal overhead. It also maximizes code over documentation, keeping this concise and making it a ‘quick read’.

Leave a Reply

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

You may use these HTML tags and attributes:

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>