In this post when i say documentation i refer to documentation that can be found in the source code. Still the things i examined are related to general system documentations (specially in case of agile methodologies).
Comments vs Documentation
Comments are generally added next to some logic the developer created to solve a specific technical issue, iterating over the posts that had the most views, or accumulating taxes, etc. Comments can occur multiple times in a methods body. And they can do a good job to help others understand how you solved a problem (hopefully not when they are debugging your code...).
Documentation in my interpretation are coming from a higher POV and can/should not necessarily discuss how the actual function is implemented. Than what should it discuss?
a.) The contract for the method
A contract defines your rights and responsibilities, as well as those of the other party. In addition, there is an agreement concerning repercussions if either party fails to abide by the contract.
What are the rights? Your rights define what parameters you can pass to a method, whether they can be null, or simply have value or not, what return values can you expect from the specific function
What are the responsibilities? Your responsibilities define what parameters you should pass to a method and what type they must have. The contract should define what error messages you should expect (in Java these are the @throws declarations).
Why do we need this? Tipically developers have a look a methods signuture and they see what they should use as parameters and what results they should be expect. Anyway the methods name will tell you what it does! If life were that easy. Also many times i hear people saying: "I believe a good code is documenting it self". Okay fine. That can be true why not to do comments. But how could that be an excuse to write documenation (i.e. javadoc)? Good or bad code it is other people will not necessarily have your code at hand maybe only the interface of your module.
Let's see a bad and a good example here.
The bad example:
As you see i am trying to use a method called
calculate because a developer told me it can be used to calculate what money i will have left after paying the taxes. So far so good. I have a variable which holds the amount and another one which is the VAT. As percentage because this is how i represented it. I see the calculate method gets the VAT as a second parameter. But in what format? 25% ? 0.25%? How should i know? It's easy! I can check the methods code. That's cool. If it's my code or some code which is close to the code i'm developing. But if it's another module it is less likely that i would like to check my self. I might not even be able to. As simple as that I like to look other people's code as an API. Not to mention if it is really an API coming from a 3rd party tool. And we all know that an API needs the following attributes:
- the interface should not change
- it should be easy to code against
But how do you code against a method which you don't even know how to use?
The good example:
In the scenario above you can see the evidences that my brain capacity is limited. I can't even remember how to use a StringTokanizer (okay i can rember, but i still like to double check). But i hardly need to. Since the creator of the StringTokanizer created in a proper API concept. I could check the source code to see how it works (generally it is good to see how the Java API works) but i don't need to. I read the documentation (javadoc) to see what i should pass in and what i should expect.
Bottomline: it is mandatory to create documentation for your methods so the users will be able to know how to use it. And this leads us to end up with proper method contracts.
b.) The contract for the class (module)
Same applies to classes. In my previous job i was responsible for a group of developers. Generally i tried to follow where the code goes by browsing through the nightly build. Once i opened the error listing for a particular class. The name of the class told me nothing about what the class was actually doing (my intention was to see what business function could be broken). So i opened the class in Eclipse. Guess what? No javadoc of course but five thousand line of diverse functions. How can an earthling possibly find out what this class is doing? I had to ask a senior developer to summarize me what is the purpose of that module is. I was shocked to realize that it was clearly breaking the
single responsibility principle. How could this happen?
Whenever you create a class or a module it worth to stop for a moment and have a think on the following items.
- By selecting a proper name you inevitably making a decision on what the class supposed to do. By just another GeneralServiceManagerHelperFactory class you are just adding complications. What does a GeneralServiceManagerHelperFactory do?
- By creating some short javadoc for the class you are making other developers life easy. Because they can see if this module is useful for them or not.
Every now and then we all fall into the trap of trying to add too many functionalities to a class. So that is something you want to avoid as much as possible. But that is not part of our topic. I found the two points above to help me subconsciously make a plan upfront. It will result in many smaller classes with limited responsibilities instead of having a bunch of monster classes.
Okay so that's all what i had in mind on contracts and documentation. This summary was trying to be practical. If you are interested to learn more on the principles i strongly suggest reading this book:
As always i'm very curious to see what you think about the subject so please leave a comment.
Happy coding!
