You Need More Than Unit Tests
More and more lately I’ve run across programming conversation in blog comments which indicate a worrying trend. Quite a number of programmers don’t seem to view internal or external documentation as important. But why? Here is a minimum level of documentation I would expect in a project regardless of the programming methodology of the developers…
Internal Documentation. Who wrote the code? When was it written and last amended? What does the code do – is it a class which defines the behaviour of bouncer balls in a beach ball game? These should be included in a comment at the top of every page of code. And let’s face it that takes around a couple of minutes so its not going to break anyone’s day typing it in there. The next level of internal documentation are comments before each method or function. This should at least describe the function and it would be good to have the expected inputs and outputs available so new people picking up the code don’t have to guess what you meant when you named the method integerQuad(int k, int l). Define the expected parameters k and l as well as the expected boundary cases. Don’t underestimate the next coder’s ignorance about the way you think (or you’re own ignorance early next week).
External Documentation. Again this should contain the details of who wrote and edited the code base. Why was it edited? Were there specific errors which caused the previous iteration to fail? There should be some form of error logging so that when Jimmy runs into the same problem June fixed last week he might find the solution in the documentation. Otherwise every person could be out there trying to reinvent the wheel as a series of one-man bands. And don’t forget version control.
Next you should be keeping time reports about your productivity. This can be used to hone down your quotes over time – how long does it take you to write a certain kind of class or method? Also, beyond creating documents which will aid your fellow programmers (or replacements) there should be user documentation written from an entirely different perspective.
That’s a very brief overview so please don’t shine me up like a quartz-halogen wigwam. The point is documentation has its place when you perform software engineering.
My concern then is where people pick up books and get the idea that unit tests are somehow entirely enough. No code comments required, no external documentation. My question is how much more expensive do you think it will be if nothing is documented? Its all fair and good to be a brilliant coder. You might be able to hack your arse into a five star code magician but at the end of the day you have to be a part of a team. Does that make sense? Unit tests have their place but they shouldn’t be the only artefact that tells how your project is stitched together. I’m sure your financing stakeholders would expect more than printed out unit tests to explain what you’ve achieved so far.
Anyway that’s my little rant for the day. I don’t understand how any professional programming related business can go without documentation even if there are unit tests coming out of the projects bum in superlative hiccups… eventually someone else is going to have to read that code and understand what you meant by integerQuad(int k, int l).
