Guest post: Incremental reshaping

A couple of dear friends and I are (too) often having discussions by email, on topics that range from video games to politics, and mostly software development and design in general. A while back, one of those discussions started after sharing an AltDevBlogADay article on optimization. As we were confronting our experiences on optimization or lack thereof, one of them, Rubix as we call him, made some insightful points by explaining an approach he would call “incremental reshaping”.

When I found myself coming back to his mails several times, I suggested he turned them into an article. With his permission, here it is.

Incremental reshaping

The most common case at my work is to stumble upon slow spaghetti & copypasta code, full of lists of hashtables of lists, all within a big class with 45 methods hitting them directly. So I start off by pulling the data out and into new classes, to encapsulate it. Then I clean up the code that uses them, by factorizing all similar operations into methods of these new classes, as well as trying to come up with good names for them (I know this part is done when the original data structure ends up being private in the class).

This way the operations eventually make sense, and I can at last understand what the code is trying to do on a higher level. Finally I can simplify the calculations and rework the (now hidden and loosely-coupled) data structures to best match the most critical uses. All of this has to be done incrementally. Do one change at a time, and then pause to look at the new code to search for the next simple refactoring. Otherwise, your changes will not be optimal.

Once everything is clean, if it’s still too slow, *then* optimize, even if it means to add complexity by removing good abstractions. Code that is complex in a particular way because that’s what is time-critical, will be both more maintainable and faster than code that gradually, without global monitoring, evolved into something complex everywhere, uniformly slow for many reasons.

Encapsulation rarely affects performance in my case. I work in environments where the cost of a function call is negligible, and functions are the most common abstraction tool.

Now, an example.

Yesterday, I saw a four parameters function I didn’t like. I first created a tiny class to contain just that function (all call sites became “new Foo().method(a1, a2, a3, a4)”), then I moved two of these arguments, that were often the same, into the class (call sites would become “new Foo(a1, a2).method(a3, a4)”). At some places in the calling code, I was then able to cache and reuse the instance of “Foo” into a local variable, because “a1” and “a2” were the same for several calls to “method”.

From there, I found that the calling code was more or less always doing the same kind of things before calling the method, so I moved that stuff to a second method of Foo (it turned out to work so well that the first method became private). Then I noticed a loop that was calling Foo’s method repeatedly, so I wrote a new method that took a list as a parameter. (I also ended up finding an appropriate name for Foo!)

Now I ‘could’ also have done it the hard way: enter the zone, stare at the code for a while, think a lot, decide that I wanted it to eventually be like this, then put my headphones and implement it directly instead of going through any of the sub-steps, which are unnecessary when you can fit all of it in your head.

But incremental reshaping has several advantages:

  1. No need to know in advance what to do from begin to end, ideas come as you go.
  2. The possibility of changing your mind more easily; you had an idea but you may find a better one later.
  3. You can take advantage of the compiler & IDE at each step, to always know what state your code is in, and make sure nothing was forgotten, thus avoiding bugs and going faster. At a given time, it’s always the same message from the compiler, so it’s easier to read.
  4. It keeps your code compiling and correct between every change. Also, for every little change, if you know your tools well you should be able to convince yourself that it breaks nothing.
  5. It diminishes greatly the cost (and the pain) of being interrupted while focused on your changes.

Matrix and Quaternion FAQ

Although its caveats, a classic on the web and still a useful resource, here is the most recent version I found of the: Matrix and Quaternion FAQ.

Warning: the document I’m linking here has been orphaned for many years and might still contain errors. Moreover, the links are broken on this version hosted on Java 3D (they’re not on the even older, Princeton version).