Document yourself a better programmer!?

Document myself a better programmer what have you been drinking!? My code is self documenting you might say but hear me out and let me tell you about something that might motivate you to write better and more extensive documentation.

Programming are by far one of the most fun things I know how to do, and on the same page documenting my code might be one of the most boring things right after watching pain dry, still it has to be done and quite frankly since I hate poorly documented projects it would be rather hypocritical of me not to do it.
The love for writing code and my dismay of documenting means that the way I have been working for 20+ years now (although at the age of seven, since I copied everything from books and noticed what the code did I would like to argue it was rather well documented – I just could not read the language it was documented in!) is to first have fun and write the code and then be bored and unmotivated while I quickly scan through the code throwing in comments and documenting what it did. But.. a few years ago I decided this had to stop, I decided to become a master at documenting my code (famous last words) – and while the road has not been straight forward this is what I found.

Documenting your code early makes the documentation and the code a lot better!

When you stop writing code often with the code fresh in your mind it’s easy to see that this will add clarity to the documentation but I have also noticed a great improvement to my code. The code is improving greatly because when you go back to document a function or algorithm you see a way to make it faster, better or just more readable (not to mention all the bugs that you find and fix).

Administrating old code months after you wrote it becomes a lot easier!

If you don’t write down how your code works you will take it in the shorts the day you have to go back and administer old code, if you are a private company it could very well be what breaks your company when you have to spend long non billable hours digging through code just to make a bug fix or small change documentation can very well be what saves you in the end. When you write the documentation from the start it is also easier to bring new developers or testers  up to speed.

Considering the costs, especially if you are utilizing specialized testers from a consulting firm. If they can come in from the start with a few hours of reading understand what is requested and how far you have gone they can very quickly become productive members of an agile team, if they have to wait until the product is done to find the bugs (yes they will find bugs get over it) it will delay shipping, make it much harder to fix the bugs and increase costs so documenting early and often saves money!

You will know how the requirements have changed over time.

If the super sleek and innovative system you once wrote is now slow and filled with fixes that makes it a night-mare to administrate it might be easy to blame the developers for not making the job right, good documentation may show that the customer have changed the specifications more often then the coders ate pizza and requested more unspecified features then a greedy kid on Christmas eave, at the very least it will point to were the costumer and the programmers understanding of the product differed and be a tool to discuss and reason around.


How do you and your company work with documentation, have you made any changes from the regular ways of documenting code and how is that working out for you? Please leave a comment!

Best regards
//Karl-Henrik Nilsson