Fog Creek Software
Discussion Board

Understanding someone else's code - how?

What is the best way to understand someone else's code, assuming that you were required to maintain/enhance it?

Here's my 2c: in my 18+ year IT career, I have found that reading program listings in hard copy is the most effective method for getting a handle on another person's program code - before one can begin maintaining or enhancing. Now, this may be viewed as ancient, archaic, procedural or whatever - but I'd like to get a sense of other opinions out there.

Full Disclosure:: I am not too familiar with OO and spent most of my coding life tinkering with COBOL. My question above is aimed at the more contemporary programming environments like C++, Java, etc.

Jagdish Bajaj
Tuesday, April 30, 2002

Assuming you have a program that compiles and runs, I like running the program through a debugger to watch the code "in action".

I also like hardcopies (2 pages per side of course), on canary paper.


James Wann
Tuesday, April 30, 2002

Extreme way: Refactor!

If I have someone else's code to understand or maintain - I writing a unit test for part of it (this will help me to understand an interface of the part.
Then I refactor - give more meaningful names for procedures, variables. Extract chunks of functionality into methods.
Several times I'm refactored other's code even if I had to leave original version in the project (there were no unit test and there were no time to add them).

Roman Eremin
Tuesday, April 30, 2002

I like to get a hard copy, and I like to run through the code with a debugger. Line by line.

I often wonder why it is that I dont get as much from code displayed onscreen as apposed to printed on paper. Anyone know why this is the case ?

Yes I print 2 pages per sheet and print on both sides. Ill have to try the canary paper.

Regs -

James Ladd
Tuesday, April 30, 2002

I always rewrite from scratch, that way I get code that I understand completely - just joking, I think hard copy works because you can flick between pages and spead them out the way you mind is working.
It all depends on the complexity, if its easy stuff I dont need the paper, if its a bit meatier then sometimes I like certain bits in print, I always pretty print it though, smaller font, line numbered, even with lined loop and if/else/end stuff too.

Tuesday, April 30, 2002

> What is the best way to understand someone else's code, assuming that you were required to maintain/enhance it?

My doing that is usually just another project, not a whole career. So I don't try to understand it [all], instead I try to find the place[s] where I can inert whatever new functionality they want me to insert... just understand where to insert, and how to rebuild and retest, and ignore as much of the rest of the code as possible.

Christopher Wells
Tuesday, April 30, 2002

What's canary paper?

Tuesday, April 30, 2002

Printing the code on A3 paper is great, as when you spread them out on the desk it's like having 4 17" monitors.

Matthew Lock
Tuesday, April 30, 2002

At first, when I stopped blaming the coders for not having good design docs, I realized I had to think of ways how to implement it first.  When I have no idea of the problem space, it takes me a while.  But after all, it's like trying to gauge the truth of speeches -- if you have no knowledge of the subject, your impressions are extremely suspect.

Because of this, I make sure I do my research.  (And I generally distrust teachers to be complete. ;-)

Greg Neumann
Tuesday, April 30, 2002

Printing the code on paper is very helpful. Can see a lot of it at once and can circle things, draw arrows, etc. Being able to mark things up is so important (and also part of why ebooks are no where near ready for prime time). Printing out though I do save for particularly tough problems.

Correcting/rewriting the comments is helpful, especially since often they will be obsolete.

X. J. Scott
Tuesday, April 30, 2002

: ) --> if it's Java code, the best way is of course to use Juliet ( ). With Juliet you can browse through the code by following links from uses to decls, and from decls to info about where and _how_ that decl is used ("Who writes to this field? Who overrides this method? Who calls this method (directly and/or Via overridden ones)? ...").

If it's C/C++ code, I find SourceInsight very helpful ( ), again because it helps me browse through the code, which a printout doesn't.

[Discl.: Juliet is produced by my company, infotectonica.]

Carlo Walentiny
Tuesday, April 30, 2002

Paper is better than screen - you can get
several routines on your desk at once and see how they interact.

I never refactor in order to understand, because I might break something I don't understand (if I had 100% confidence that my regression suite was exhaustive I might, but that has never happened.) I do however
write comments in the code as I  understand bits of it. Again I don't need this if the code has been properly commented by the author, but this has never happened.
(To be fair people are probably saying the same thing about my old code somewhere - good comments are the ones that tell you what YOU need to know, and that tends to be slightly different for everyone.

David Clayworth
Tuesday, April 30, 2002

> What's canary paper?

Yellow stuff, like legal pads. Black on white is sometimes too much contrast for my eyes and they'll bug out.

James Wann
Tuesday, April 30, 2002

For DB stuff, look at the Entity relationship diagram.  You can produce a good one from ERwin/ DB Visualizer, and even access has some success. 

For OO Code, go to the UML.  If it exists.  Which it probably doesn't

Good IDEs help because you can jump for Ref to usage.

The Debugger Idea is great.  One of the line Items of either code complete or writing solid code, (I forget which)

Tuesday, April 30, 2002

For people owning Together/J (I think the free solo version does it too), it is possible to see the call trees without running the program (useful when a resource you need is not present). It is a kind of debugging without having to run... It helped us once to understand a ton of legacy crap we got.

Philippe Back
Tuesday, April 30, 2002

I usually start out by skimming through the class definitions to heuristicly build up a dependency graph between modules.

Then I proceed to find the "entry point". This can be hard in a GUI app, but go for the most basic functionality and concentrate on that first.

From the entry point, I create a call graph (following the most likely path through code -- don't bother about exceptions, error handling and stuff like that at first).

Using such an overview you can often figure out where bugs are located, what could be refactored, or where new code could be inserted.

Roland Kaufmann
Wednesday, May 1, 2002

I find that the best way to understand someone else's code is to use it.  When I'm in a position where I am expected to enhance someone else's code right away, I find a way to trace how that feature works from the UI on through the code and make that change.  Then another one comes along.  After a while I start to see patterns in the system and it usually hasn't taken me more than a few weeks to get a decent feel for the layout of the code.

I may be in the minority, but I find reading code on paper harder than it is on screen.  I think that's because the page breaks wind up breaking up functions often.

Wednesday, May 1, 2002

*  Recent Topics

*  Fog Creek Home