Refactoring: Making your code suck less

ziggy on 2005-03-02T17:08:59

For the last six months, I've been working on a project at $WORK to bring order to the main webapp our team has built over the past N years. My task was basically, "make this code suck less", modulo some constraints like use the same environment, and make the new code work side-by-side with the old code. Fair enough, just a [long overdue] refactoring project.

The project has gotten to the stage where we are starting a slow rollout of this codebase, and now documentation is the focus. The problem is, I've got all of this new code that uses some OOP-fu to clean up some long-standing issues, and there's no clear way to document the little beast. It's the Inside Macintosh[1] problem all over again!

Feels like it's time for a little more refactoring. Time to clean up the new code so that it does the same thing, but is easier to document and extend. That'll make my immediate job easier, but also make it easier for new developers to adopt.

Why more refactoring now? Because refactoring is like an oil change for your car. The longer you delay, the worse it gets, and the more damage it does. Delay long enough, and everything seizes up, which leaves you two options: major remediation, or a total replacement. Refactoring (or regularly changing the oil), is a minor cost to pay for ongoing high performance.

The XP folks say that a day without refactoring is like a day without sunshine. That's a pretty extreme view to take when dealing with management that treats refactoring as expensive retrograde work producing no net value. (Fortunately, I'm not in that position. Now.) Maybe the answer is the 10% solution: can you afford to spend one day every other week to make your code suck less? Not fix every problem, but just make it suck less?

[1] The original edition of Inside Macintosh (later known as Inside Macintosh, Volume I) was a reference book of 25 chapters, each written with the expectation that you had read and fully understood the other 24 chapters it built on.

Ego

Ovid on 2005-03-02T17:18:39

You realize of course, that your focus on refactoring is nothing more than a reflection of your bloated ego.

And no, I'm not serious. Cringely was smokin' crack.

Re:Ego

ziggy on 2005-03-02T17:45:07
Yeah, and Joel thinks refactoring is wrong, too. Or maybe he doesn't. All I know is that he writes about a different world of software than I'm dealing with.

Just a little refactoring?

scrottie on 2005-03-06T22:15:39

Funny how the structure of the code requires more adjustment than the algorithms themselves. And if you're like me, after you take something apart and put it back together again, you have a few dozen screws left over. And sometimes it is easier to fix something than to document it broken - but usually not. And I won't dredge another buzz-phrase into it, but it's nice if something has already been documented and you can refer to the documentation for another piece of code (even if that thing being documented is ultimately just a kludge). If you've ever purchased Haynes or Chilton manuals, you'll notice that the vast majority of the text is cut and paste from another manual for another motor vehicle. I've found programming a lot easier (specifically, the documentation/program complexity delimma) since I've granted myself permission to use any reasonable construct as long as the construct itself is documented somewhere on the 'net and I only have to document why and how I've used it. I'm not sure if this would help you or not. I don't know how ugly the code is. Whomever gets it next is going to find it twice as ugly as you find it and probably just want to replace it. If they can replace bit by bit rather than all at once as you did, they'll probably be grateful. So there's an argument for not even bothering to document and just write unit tests. And here's an argument for slow, incremental refactoring: by "sleeping on it", perhaps for a week or a month at a time, you'll get a better sence of what your priorities should be and this will prevent you from wandering down endless and not particularly useful roads - these are the roads that make programmers look like they like to refactor for the sake of refactoring when they go down them. And sometimes it's hard to get a vision of how a program should be out of your head when it manifests, and then you're taking the first road, not the best of a small lot. Okay, enough of my blather.

-scott