See email from Casey
The email is gone. Nobody at the practice remembers a Casey and nobody here can tell me who wrote the comment, which is dated April 2014. So I’m not sure who I’d even ask.
Here’s the comment. It’s buried in the middle of the longest function in the theme, on top of the rule that decides whose inbox a consultation request lands in. Nobody has been willing to go near that rule since.
// do not change, see email from Casey 4/14
// everything goes to the front desk, and then there are the exceptions
var inbox = 'frontdesk';
if ( $procedure.val() === 'implants' ) {
inbox = 'surgical';
}
if ( $location.val() === 'north' ) {
inbox = 'frontdesk';
}
if ( $form.find( '[name="insurance"]' ).is( ':checked' ) ) {
inbox = 'billing';
}
$form.find( '[name="department"]' ).val( inbox );The practice’s tickets have been coming to me since March. The site went up in 2012 and has been through several pairs of hands since. So I inherited WordPress plus four years of other people’s opinions about WordPress.
The theme’s main.js is around 600 lines of jQuery. The function in the middle of it is the document-ready handler that runs on every page, and it’s 211 lines long. I know that because I counted them, which is what you do in the first hour when you’re really just having a feeling.
Four levels of nesting and a $tmp2
The feeling was contempt, obviously. The function is 211 lines long and there are no tests anywhere in the project. It nests four levels deep in places, and there’s a variable in it called $tmp2 sitting a little below a variable called $tmp.
And I’ve done this enough times now to know that the feeling is useless and most of the time it’s wrong on the facts too. The people who wrote this were not worse at their jobs than me.
They worked on the same code for years under deadlines I know nothing about and against requirements nobody wrote down anywhere I can find. Every strange thing in that file is a fence standing in a field where I can’t see the animal. That’s Chesterton again, who shows up in my head more often than a dead Edwardian essayist really should.
More to the point, somebody is paying us to change this thing and contempt makes me want to rewrite it. A rewrite is the most expensive way there is to find out what a piece of software was doing.
So I’ve ended up with a fixed order I read things in, mostly to stop myself from having an opinion before I’ve earned one. It’s just always the same, which is the part that does the work. The order is protecting me from my own first hour.
The scenic route
I start with the site, not the code. I click around it as a patient before the editor is open at all. I want to know what the practice does, what the pages are, and what happens if I put a bad email in the consultation form.
You can’t understand the shape of a codebase without the shape of the thing it does. I’ve watched myself read three files deep into something that turned out to be a feature nobody has used in years.
The backups come next and I’m still not in the code.
main.js
main.js.bak
main-old.js
main-old2.js
main 4-14.js
main_BACKUP.js
main-FINAL.js
slider.js
slider-old.jsThis is probably the highest-yield hour available on a site like this, and I ignored it for most of my first year. Nothing here is in version control, so the copies people left next to a file before changing it are the only history there is. They’re a log nobody meant to keep, and they tell you things the code physically can’t.
You can see which files somebody was nervous enough about to copy first. The file with more copies than everything else put together is where the work on this site actually happens. A file with none is either solid or dead (one grep tells you which).
Here they answered three questions inside the first hour. The copies have at least four naming habits between them, so at least four people have been in here. I can’t reach any of them. That’s a completely different project from two people who are both still on email, and it changes what I’m allowed to assume about consistency.
main.js has the most copies by far, so the scary file is also the working file. That isn’t always true and it’s worth knowing before you plan anything.
And once I’d diffed them in pairs, the routing rule came out the same in every copy back to the oldest. The slider setup above it is different in nearly all of them. So it’s one file moving at two speeds.
Then I read whatever the theme says about itself: the header in style.css, what functions.php enqueues, and which plugins are active. I’m not there to change any of it, just to read what the site thinks it is. An enqueue list is a statement of intent. The interesting history is usually in the gap where the intent and the code disagree.
Then I work out the entry points, or how a URL turns into a file. On WordPress that’s the template hierarchy plus whatever the theme has bolted onto it. It’s the only map that’s reliably accurate. Until I have it, I’m reading paragraphs out of a book with no page numbers.
Then I read the templates. They come before the scripts on purpose because the output is the part I can check. I can load the page and find out whether I understood it. Being able to check yourself cheaply is worth a lot when everything is unfamiliar.
And then I finally get to the 211 lines and I bring a question.
Understanding is not a task
This is the part that took me the longest and it’s the one I’d actually pass on.
“Understanding the codebase” has no edge and no finish line. If that’s the goal then you’ll read for three days, feel worse than when you started, and retain none of it. I’ve done exactly that (and put the hours on a timesheet).
Showing up with something specific works. Why does the phone number in the header come out different on this one page? Why does the gallery skip a photo on its second page? What happens between somebody hitting Submit on the consultation form and an email arriving in somebody’s inbox?
Then you read only what’s on that path and follow it end to end. You come out knowing one whole thing instead of nine partial ones.
Do that a few times on different questions and you’ve got the codebase sideways in a way that actually sticks. It’s slower to feel like progress but I think it’s quite a bit faster to be progress.
Hands where I can see them
Refactoring while reading was my worst habit, and it took a bad week to break it. The urge is enormous because tidying feels like progress and reading doesn’t feel like anything at all.
So you rename $tmp2 while you’re in there and pull a couple lines out into a helper. By the end of the week nine files on the server are different in ways nobody at the practice can see. There are no tests under any of it and no history to diff against. You can no longer tell which of your own changes broke the thing that’s now broken.
Now I keep a list in a text file instead. Every time I want to change something I write down the line number and what I’d do about it. Then I change nothing for the first two weeks. A good chunk of that list turns out to be wrong once I know why the code is like that, which is a very cheap way to be wrong.
When I did finally split up those 211 lines, it was because a ticket had me change the slider and I only pulled out the slider. It went into a new function that the big one calls, so the risky piece is small and isolated and I can look at it on its own. The rest of it is exactly as it was, ugly and correct.
It does look wrong
For the record, that function was three things stapled together, which is what it always is. It was about 90 lines of slider setup, about 80 of the mobile menu and the smooth scrolling, and 40 of a very specific rule about whose inbox a consultation request lands in.
Casey’s email is gone and I’ve stopped looking for it. That comment is still the most valuable thing in the file because it’s the only part of it that tells me a person was surprised here once. It’s sitting on the exact 40 lines I’d have cheerfully simplified in week one on the grounds that they look wrong. Those three words get read every time somebody opens that function, which is more than the style guide I built for my own site earlier this year ever managed.
They do look wrong. They’re also the business. I feel like most of the ugliness in an inherited codebase is four years of decisions showing through instead of anybody having been bad at this.
None of the above is a methodology. It’s an order, and the order exists to buy me two weeks of not having an opinion. The opinion I have in hour one is always the same one, and it has yet to be right.
Casey is the one thing no reading order gets me. If this site were in git, git blame on those 40 lines would hand back the commit that added them. Even a commit whose whole message is updates comes with an author and a date. The author knows who Casey is, or at least what the email said.
Here there’s a comment, a backup called main 4-14.js, and a front desk where nobody remembers the name. Git wouldn’t have made that function any shorter or any less ugly. It would have kept the one fact I actually need, which is who to ask.