Javadoc/Comments in Code

A work colleague "Richard Paul" suggested some very good ideas about what things should be included in javadocs/comments when coding. So I thought I should write about it to spread the knowledge.

Comment design decisions and why you did it that way

There was a situation at work were we wanted to know why a particular variable was used in a calculation over another variable. Then we started to think back to why we did it that way and this had happened a while ago so not a lot was recalled. We needed to know this because we needed to change the variable being used and couldn't recall if there was any special reason why we used that variable.

But if we had documented in the javadoc why we used that variable over another variable that would have made things much simpler.

Most of the time developers document how their code works in the javadoc. This is good when the code is complex and hard to understand. In the ideal world the code should be well written that very little javadoc is required to explain what is happening. But we believe it is also important to document why you have done something in a particular way. Also any coding design decision should be commented.

I will give you an example to better explain what I mean.

I had to implement an interface for a listener to perform a particular task. Now the event for this listener had 3 different event types.

One option would be used to implement the interface directly and use if statements to handle the 3 different event types.

Another option would be to add an abstract class in the middle which would handle the if statement and delegate to 3 abstract methods. So instead of implementing the interface, you extend this abstract class and instead of implementing 1 method, you now have 3 abstract methods to implement.
The reason I did this was because the code was more clear as to what each method was doing. Also if in the future we wanted another implementation, we could extend the abstract class and the common logic is still in the abstract class and it would be easy to substitute classes.

So, some of the reason I outlined above should be added to the javadoc of the abstract class. So that when someone looks at the code in the future, they will understand why I used an abstract class instead of implementing the interface directly.

Company's might have procedures in place to write supporting document about the code. But this might be hard to locate and might take time. But having some of the reasons in the code makes the information available quickly.


Comment your unit tests

Another place that comments become very useful is in unit tests. Testing code is very important and I might write another post explaining why later on.

So what do I mean?
Each test case you write should be testing a particular case. So sometimes its a good idea in the javadoc of the method to summarise the input and output of the test case. Now if you are creating all the input data inside the test case, then this javadoc might not seem very useful. But if you have created your input data in the setup method of the testing class, then its not very obvious what are the inputs. Creating the input data in the setup method reduced redundancy and is the logical thing to do to make your tests maintainable.

I will give an example to explain what I mean.

public class TestPerson extends TestCase {

protected void setUp() throws Exception {
Person person1 = new Person("name1", 10); // name and age of person
Person person2 = new Person("name2", 11);
// etc
}

/**
* The people should be allocated by name
* Data:
* Person1 - Jane
* Person2 - Bob
* Person3 - Steve
* Outcome: a list in the order Bob, Jane, Steve
*/
public void testAllocatePeopleByName() {

}
}

This is just a simple example demonstrating the concept of commenting your tests.

Now if that Test Class was very long, that javadoc becomes very useful. Instead of scrolling to the top of the test to see the details of the input data in the setup method, you have a summary in the javadoc of the test method.
Maintaining the code and tests now become much easier. If you wanted to maintain this code in the future or if someone else looks at it, they would be able to understand and comprehend it much faster saving time thus money.