Documentation: For the greater good

I find it ironic how most programmers hate adding documentation, but then complaint about other software not having enough documentation. While working on some bugs I would thank whoever added comments and curse who didn’t. Therefore its only fair that I add comments to my code even though it takes more time. Its time well spent.

While working on some new features I was surprised on how much time I spent adding inline comments to the code. I had created 6-7 classes and was working on them in an ad-hoc manner, going back and forth adding methods, logic etc. I witnessed the following benifits:

• No need to decode variable names, you know exactly what they do.
• Javadoc for methods, saves you time from trying to figure out what it really does.
• If you came up with a nifty little trick to solve a problem, it is essential you add comments or else it’ll take you longer to try and understand it later.

These benefits are multiplied when you work in teams. Code reviews take less time and there’s less chance of misinterpretation. The reviewer in frustration would just reject your changes or even worse approve them, only to find a bug later.

I believe implementation isnt fully complete unless you have finished documenting it. Yes Yes I know you have deadlines, but if you were to just add comments while writing code it wont take you any longer.

So in summary even though you might hate adding documentation, DO IT ! Someone will thank you later when they see your code.