Documenting Source Code - How It Was Driven Home to Me

This happened almost two decades ago. It was my first startup. We had built a radar Moving Target Detector using four DSP processors, plus another DSP as a controller. I had taken it from proof of concept, to field trial, to ruggedized prototype. Over that time the team size had grown from one (me) to three.

The ruggedized prototype was now to be put through acceptance checks. We gave a final check and then packed it for transporting to the customer's site. When we assembled it, and put it into operation, the ouput would not settle down as it was meant to. That got me into a flap. I was sure that during transportation some damage had been done to the hardware. I had visions of doing a messy hardware debug on the customer's premises. Luckily, I decided to sleep on the problem.

The next day I asked one of my engineers if anything had been done to the code that was in the EEPROMs. He said that there was a long sequence of code which did nothing but write zeroes into the RAM. He had taken that out. The data memory was no longer initialized.

So was my engineer at fault? No, I was. This was code that I had written almost at the start of the project. The purpose of the code was clear to me. But I was no longer "in contact" with the code. And I had failed to document it.

I have since then, been rather fanatical about documenting the intent of any block of code. Documenting the WHAT [is intended to be acheived], and the WHY [it is important that it be acheived]. The HOW is not that important; the code should say that - unless of course the code is convoluted. But then one should not be writing convoluted code in the first place:-)

This incident led me to formulate my extension to Murphy's Law:

If anything can go wrong, it will - and it will happen in the presence of the customer!