Getting It Done “Write”

The software development industry has a problem. Most of us are lazy. In this cling to the “do as little as possible” attitudes, we lack the necessary desire to document what our code does. Granted, if you are anything like me and write “perfect” code then you shouldn’t need to document your code right? Wrong. Documentation is the sort of effort that proves fruitful later on in a couple of ways.

The Example

Lets assume for a minute that you are the star programmer. As such you are a wanted person. The team developing Flaglets wants your time and effort to write a backend API that allows access to the database and that the team developing Rewquicks needs you to write an AJAX toolkit that supports loading of everything in under 3 seconds from request to finish.

You know you can do this work. Hell, for you it’s easy! So you throw on some tunes, and start pounding away. In the sprint you have managed to finish both tasks plus some. Again, you have reasserted your position as company superstar. All is good in the land of you and you move on to your next set of tasks.

The Maintainer

The product has been working for some time but a client found an issue with the way the Flaglets API is working. The data seems to be coming back mangled. You can’t work on the bug as you are fully allocated to all the current projects at the company.

Insert The Maintainer. This individual will have to run through your code and fix your bug. Oh and did I mention this is a P1? Well it is. Now s/he has to trudge through code to figure out what the internals mean. Leaving aside any inherent problems with the code itself…how am I to start working with this code?

The Maintainer can ask questions but that generally doesn’t provide enough context to get rolling. That then means that s/he is left to either return to the developer with more questions, which is not always possible, or fight with the code. The latter is usually the case.

You as the Developer

So, you are still that amazing developer. You are a code ninja, but you’ve been away from this code for quite some time. It starts to eminate a distinct odor; the scent of “code stink“. You start thinking that it’s about time you reworked parts of your code. But you start to run through that wretched smell and although you are and were the awesome superstar…you got better. You have realized that you really did not know what you were doing when you wrote that piece of code.

I bring this up because it’s important. Your code will develop this stink. If it doesn’t, you should be concerned for your job as you are likely on your way out. ;D

Anyway, the point is that you have to figure out what you meant when you created this piece of junk so that you can make it better. This now puts you into the same situation as The Maintainer.

Why It’s Important

Your documentation may help save the day. Not only will it save time and effort, but it will save a few hairs from quickly turning gray! Think of the hairs! When you document your code you are preparing any future readers for whatever it is that your code does. The main reason that documentation is so important is that it can help prevent bugs!

There have been many occasions where a decision was made to implement something a certain way because of a limitation or something else. Without commentary, anyone looking at that code without context might think to refactor it, but that could be detrimental to the functioning of the code.

Also, I am in a position where I review a good deal of code for quality so that we are doing things efficiently and effectively. I often have to ask what the purpose of some code is when a little notation would go a long way and save me from having to ask.

Digest in Moderation

Now, if you do no documenation, then get to it, but keep this in mind. As with anything, moderation is going to be your friend. Putting useless or obscur comments in your code can actually harm your effort. Find the balance. If something is not obvious by the code or you are unsure as to whether to comment, write a comment. Err on the side of caution. But, in all of this you need to make sure that you are writing useful documentation. Making a note about something that happens 15 lines down is fairly useless, but stating that the parameters should be a value of type X and will throw an exception otherwise is great.

Happy documenting!