Search This Blog


Friday, March 7, 2008

How Not to Read New Code

There is a great article on how to read new code, written by Tim Ottinger. Having maintaining my ex-colleagues code for sometime, I believe that I do have something to contribute here.

I assume that you are dealing with code that
  1. Have no unit tests
  2. Exhibit strong code smells
  3. Are deprived of its owners, meaning that the ones who wrote the code is no longer available for consultation
Here are the don'ts:
  1. Don't believe in comments. Comments, be it XML comments or any other forms of documentation, are vague at best and misleading at worst. They are often outdated or simply false. In any case you are better off with reading the code because the only comments that count are code.
  2. Don't assume that every piece of code is intelligent or meaningful. No matter how smart a programmer is, he is bound to make mistakes. What more to say about someone whose code exhibit strong code smells. If you find a method obfuscated or is simply talking nonsense, you need to refactor it mercilessly in order to get any sense out of it, with or without unit tests.
  3. Don't change the code without a strong team of testers. As mentioned above, you need to modify code without unit tests. So you need another safety nets to cover you. A strong team of testers would do the jobs. Make sure that they test every possibilities related to your code changes. Expect your bug tracker to be filled with thousands of bug reports.
  4. Don't ring up the original coders for help, if they have left for a long time already. Why? Simply because no one can understand poorly written code, regardless of whether it was written by the authors themselves, or any other people after sometime.


Joe Fortier said...

The Micheal Feathers book, "Working with Legacy Code" is a great resource for wrapping unit tests around old code. I've never worked "with a strong team of testers", but I have wrapped code in unit tests.

Soon Hui said...

joe, nice to hear that you have wrapped code in unit tests.

But legacy code can be hard to test, and it is not a trivial issue to wrap code in unit tests. :)

Anonymous said...

You can write wrappers to capture output and log it. Then, you can create checksums on the logs, and do "diff"s on them.

As you refactor the code, you track the sums and diffs, and make sure they stay the same.

This is pretty easy for web apps, because it's all streams. For GUI apps, you have to write libraries that log calls and proxies the calls to the libraries.

Soon Hui said...

Anonymous, thanks for tips. As you said, for web apps this is easy. But for GUI apps, I am still figuring how to translate pixels into bits for comparison :)

Anonymous said...

"Don't believe in comments"

While this is true, it leaves with the paradox of "why comment anything at all if nobody's gonna believe the comments anyway?" Damned if you do, damned if you don't. I advocate learning to trust or distrust the previous code's owner. Read a couple of comments and verify if they're still valid. Also, many comments might be general enough to still provide some comments (for instance, " // We can't do Foo here, because it'll break library Bar ") might still be useful.

As with most things, the advice of ignoring comments is black and white, but should be taken with a grain of salt.

SuperJason said...

As for trusting the comments, I agree with anon above.

If you know the developer, you might have some additional insight into how much you can trust the comments.

Nitin R.K. said...


I found the title of the post interesting, but I was hoping you would mention something about reverse engineering techniques.

I do agree with the things you say though - sometimes comments get outdated and when someone else modifies the code of the original author, they don't respect the need to update the comments.

BTW, what do you mean by "Exhibit strong code smells"?


Soon Hui said...

Hi Nitin,

By code smells I mean that the code is not properly written. There are code duplication, purely named variables etc.