Object Mentor Blog: Clues For Reading New Code

Clues For Reading New Code

Tim Ottinger — Wed, 05 Mar 2008 19:27:00 +0000

Okay, somebody just handed you a new chunk of code to work on. Your first though on opening the file is “Why, dear God, why?”. How do you get a handle on this masterpiece of clever programming? Let’s look for a few clues.

Where to start?

Documents

Why not look at the documentation? <laughs> Just kidding. You know there’s no documentation, and it’s probably not useful.

People and Interactions

You need a partner who is familiar with the code. Having a guide is better than having a map. Not only will you know where to go, but you’ll know ’’how’’ to go and where not to step. Other people are a wonderful resource. Just don’t settle for someone doing the work in front of you… the goal is to learn as much as to do.

No, really, documents!

OTOH, if you have somethng in the way of a summary or architectural overview, that might help. I’d read the abstract and look at the pictures. We’re after big-picture, so read it only, don’t trust it. Documents are seldom accurate, and seldom for long. It might be good preparation for your partner’s visit.

Use The Tests, Luke

Do you have tests? If you are in a test-driven shop, looking at unit tests is a good idea. If they’re written well, they are specifications (by example) of the system. If they’re written poorly, you know where to start your work at least. Your partner could do a great service by helping clean up the code instead of explaining it.

No tests? Uh, oh. No tests and no doc? Now you’re in trouble.

Scan the File Space

Are the classes well-named? Do you know where to begin working? If you can find code by looking at file names then you’ve got the handle you need. Your partner can help improve file naming if you find the code you’ve been handed is in ill-named files.

So you’re in a file, you have a mission. Either you have tests, or you’re ready to write some.

Sense Of Smell

What if the code is still not obvious? You have one more resource before you have to print out the listing and break out the markers to reverse-engineer your way out of code hell. You have your nose and your refactoring editor. You can use refactorings such as ‘rename’, ‘extract method’, and ‘introduce variable’ to clarify an existing method. You can spot duplication and eliminate it. Maybe you can bring it to a point of clarity, and then you will know

Deep Code Spelunking

It’s time to pour a really big cup of tea, get some food, take a couple of preemptive aspirin, and make sure your printer has paper.

Sometimes, you will have to reverse-engineer some of the code you were handed. Your only hope may be to rebuild it from the inside-out.

You might want to either copy the code to a scratch space to do this. Maybe you want to branch the project in version control. You want to be free to dig in an learn this the hard way, and make it better as you emerge from the depths.

You still can/must use refactoring tricks to capture the knowledge you gain, but you may need to take the code off line. And look for new partners.

"Clues For Reading New Code" by Patrick Smacchia

Sun, 30 Mar 2008 10:45:55 +0000

There are now some tools that can help a lot understanding a code base. Have a look at this features of the tool NDepend for example: http://www.ndepend.com/Features.aspx

"Clues For Reading New Code" by Rob Wehrli

Thu, 13 Mar 2008 16:42:47 +0000

I think that one of the most practical and immediately beneficial methods of “interfacing” with new code begins with doxygen -g and editing the Doxyfile. Granted, it doesn’t support every programming language ever invented, but it definitely covers the 80/20 rule.

Even uncommented code is traversable using Doxygen output.

Perhaps this is a hyper-extension to “Scan the File Space,” but it works well and the cash outlay is FREE + TIME.

Take Care.

Rob!

"Clues For Reading New Code" by Brian

Thu, 13 Mar 2008 15:37:22 +0000

“Why not look at the documentation? Just kidding. You know thereâ€™s no documentation, and itâ€™s probably not useful.”

LOL so true!!! :)

—Brian www.BrianDiCroce.com

"Clues For Reading New Code" by Prashant Rane

Wed, 12 Mar 2008 16:13:04 +0000

Code Analysis tools could help you here. Structure 101, Eclipse XRay plugin, Eclipse CAP plugin, MaintainJ, NetBeans UML support etc. can help you get the handle on the codebase.

"Clues For Reading New Code" by Alex Miller

Wed, 12 Mar 2008 14:57:27 +0000

Nice ideas. You might find my blog on code spelunking to be a natural companion.

"Clues For Reading New Code" by ik_5

Mon, 10 Mar 2008 06:24:01 +0000

On open source projects, I usually do grep to look for something I do know, and try to go from there… sometimes traveling with the code can gives you a lot of answers on the person who wrote it and how they think, and then it’s easier.

I have learned not to use graphics tools because they usually omit few things, so the more basic your tools are, the easier it is for you to find your hands and feet.

Having said that, it’s always good to find someone that already know whats going on, that can direct you (like the author here wrote) ;)

"Clues For Reading New Code" by dmitry

Thu, 06 Mar 2008 12:15:59 +0000

At the last SoCal CodeCamp Woody Zuill gave an excellent talk on how to use mocks for exploratory programming of legacy code: http://zuill.us/WoodyZuill/2008/01/14/nmock2-as-a-code-exploration-tool/

"Clues For Reading New Code" by JJ

Thu, 06 Mar 2008 08:14:39 +0000

Haha very good introduction. This should teach all the newbies to know what they’re getting into.