Coding sideways

Am I right that some of the hardest programming is when you’re modifying some existing code that is not quite well enough documented?

I’m looking at this scientific application, in which I struggled with all the code that leads up to drawing some graphs, and the graphs are still obviously wrong. Between me and success I have a few layers of trigonometry and matrix algebra.

Obviously the physicist who wrote the original code had some intention for the methods with names like get_x() and InverseTransform(). And I’ve gotten through about half of this stuff with revelations like, “Oh, this converts the photo grid coordinates into screen coordinates!” or “I can cut this scaling out entirely because I already have a transformation matrix on the Graphics context.”

But you know what would really help?

What would help

Just a line or two of comments on each method supplying critical information like:

• These parameters of type double: are they scalars or angles?
• If angles, are they in degrees or radians?
• Are the x and y version of these methods basically the same?
• Ergo, can I just combine the method into one that returns a PointF instead?

Look, I don’t need comments for you to tell me what your code does. I can see that. What I can’t see is what it’s assuming or what assumptions it’s making.

Where I got stuck

I don’t mind saying I got pretty frustrated with the graphing part. The code makes sense; it essentially draws hyperbolas and the axes sort of spin as the user pushes a slider back and forth. Got it. But there’s this junk at the end of the method–some extra matrix calculations–that seem to mess up my pretty curves for no apparent reason.

First thing, yes, it’s time to call the physicist and find out what that last set of transformations is supposed to be for. But while I’m waiting for that information, I’m visualizing a chain of operations that goes something like this:

1. Load data from instrument–works!
2. Basic data massaging–works!
3. Getting user input–works!
4. Cool trig calculations–works?
5. Results transformation–a mess?
6. Display–works!

My issue here is that I’m not sure my “cool trig calculations” are correct until I can display them. I can’t display them properly until I’ve worked out the “results transformation” part. But I do know that given the proper fake inputs, my display code works.

In other words, if this were a jigsaw puzzle, I’d have all the edges done.

The breakthrough

That’s the right metaphor. Because I’d been working through this code from left to right, or top to bottom I guess, adding unit tests and feeling my way through what this thing is supposed to do. But just as you don’t just go left to right on a jigsaw puzzle, you don’t have to hack legacy code from top to bottom. You can go bottom to top too!

Specfically, I took a break from trying to connect Step 4 to Step 5. Instead I looked at how Step 5 wrecks the inputs that Step 6 anticipates. What is my drawing code really expecting? Bitmaps? Vectors? Angles? A big mess of points–and if so, in what coordinate system?

At the moment this seems to be a lot more productive than trying to figure out, in a vacuum, what the Step 5 code is even there for. Until I hear back from the physicist, I’ll focus on the results and ask why migrating this stuff from VB6 to .NET breaks any of it.