Posts Tagged ‘comments’

Code archeology

Monday, April 13th, 2009

After a few years of service, the time had come for us to refactor one of the components of our system. Like many components, it was never fully specified, and had evolved overtime so I needed to do some preliminary study of the code to scope the amount of work needed and know more precisely what it was doing before starting the actual redevelopement.

This was a very interesting exercise which made me feel at  times like I was doing the job of an archeologist.

When I started looking at the code, I wasn’t quite sure what to expect.

 

Hieroglyphs

Most of it had not been touched for a while and the original developer had long gone, and because noone actually understood how it all worked, changing that code had become somewhat  taboo. Other developers would not dare approach it as if it were cursed, something that went beyond the “if it ain’t broke, don’t fix it” dogma, there was a sense that any modification was more likely to break something than do any good. And I guess the fact that some of us remembered that these parts were the results of long hours of what appeared to be tedious coding.

Other parts had been modified more recently by various developers when the new features were needed. 

What surprised me while navigating through the code, is that I could identify not only who wrote it without looking at the author on the CVS, but also the level of expertise of the programmer and the conditions under which the code was written.

For a start, I could easily identify the golden age period, when several parts of the code were beautifully organised. The author was confident in his skills, knew what he was doing, and had enough time to do it well. The different pieces fitted together within a well-thought architecture. The code was nicely commented, the coding style was consistent, errors were cleverly caught, functions were purposeful, names meaningful, etc… This was the work of the original developer, a few months after he had been working on the component, the CVS confirmed. This was like reading hieroglyphs on the walls of ancient Egypt’s temples.

I thought this was going to make my work a lot easier, maybe we could even reuse some the algorithms.

But I also found what appeared to have been developed in a period of crisis, something like a looming deadline. It was from the same author, but there were very few comments, some of the code comments were not relevant and looked suspiciously like a piece of code that had been copied there and adapted in a hurry. There were some TODO and FIXME scattered here and there. Some variables and functions had been left unused and large portions of the code were simply long sequences of instructions that had not been organised, errors were caught simply to prevent them from propagating. This was obviously rushed code, and it did not seem to have pleasant programming.

Now, this looked like I would have to pay back some technical debt… We would have to work from the few clues laying around to know what was worth refactoring…

Other parts of the code seemed more experimental, the variables names were not meaningful and function names did not correspond to what they were supposed to do, several chunks included code that was commented out and even if the code what profusely commented, it seems like it was more for the author to make sense of what it was doing than to share knowledge about the code. This could have been the work of a developer who did not understand fully what he needed to build, maybe the programmer was not given some clear specifications. The inconsistency in the coding style could be the result of a programmer learning or of several programmers participating in the code.

Overall, the exercise told me a story of the component. I knew not only what worked, but what was done, in what order and why. Even it was not all properly documented, the code was leaving clues just like that the shape of claypot jar made some 2000 years ago helps archeologist making sense of the events at the time. In the end, we felt like we were better equipped to know how to refactor it effectively.
But it also reminded us of the value of not accumulating too much technical debt and that good comments are gold.