Continuing my software learning stories series, I will talk a bit about commenting code.
One customer I supported many years ago was a Jewish cemetery. In the Jewish tradition, visiting grave sites is very important. For this reason, a database had been created that stored the location of every grave in the cemetery. This allowed the people there to easily draw maps so that family members could visit their relative’s grave sites. Unfortunately, the database started losing records. I was called in to find and fix the problem.
It was quickly determined that the database software created by the company I worked for was at fault. Now this was proprietary software which means that the source code was not readily available. Especially not externally to the company. Someone from corporate headquarters came out with the source code to help find the problem.
Now apparently, someone at another company had purchased a source code license for the software. A junior developer was told to remove the comments from the copy provided to that other company. (Mean I know!) Unfortunately, they neglected to keep a fully commented copy for internal use. This meant that we, the home office person and I, had to do a lot of figuring out what was happening in some very complicated code.
We eventually solved the problem, if I remember correctly, but it took a lot longer than it should have. Or would have if we had had commented code.
One more comments story. While I was an undergraduate I wrote some fun graphics programs. They were mostly written on punch cards in FORTRAN IV. Years later I decided to rewrite one in Visual Basic to display on a screen. I figured that I was a smart guy and it would be easy. Unfortunately, when I first ran it the program drew what sort of looked like random lines and not the cool geometric shapes I was aiming for. The mess looked strangely familiar though.
Now it turns out that in my attic I had the original card deck. I dug it out and there were comments for many of the key lines. One of them was a reminder that a key method expected degrees to be expressed in radians. Ah ha! That was the missing piece of my new program. I fed a method in radians and my new program worked perfectly.
A good reminder that we can’t remember everything and even our own code can benefit from a good comment in the right place.
The software learning stories series:
No comments:
Post a Comment