What I Learned From Inheriting Old Code

In January 2023, I received an email to my personal address from Claremont Graduate University (CGU). They mentioned that they had found my name in the project codebase and were wondering if I still worked as a web developer:

I’m writing from CGU where you did some work to develop the WordPress theme a few years ago: https://www.cgu.edu/. This was before my time, but I’m writing to see if you still do this type of development for companies. We’re considering doing a refresh on the CGU site.

I worked on their site as a freelancer, circa 2015-16, as part of a larger team at an agency based out of New York. That company is long-since defunct, but since then, I had opted to join Plank, which was a bricks-and-mortar agency based in Montreal. This turned out to be fortuitous as I would not have been able to undertake their needs as a solo operator.

I responded by providing some information about my current status, the agency I was working for and offered to make any needed introductions. The response I received seemed like they had no official timeline and that any refresh would be quite a ways out.

A few weeks later, however, I was surprised to find an email in my work inbox informing me that they were ready to move forward with a refresh and wanted to talk to us about it. They were definitely interested in Plank as an agency, our design chops and ability to provide user journey research, but a major point of interest was my knowledge of the project and the codebase.

CGU decided to engage our services and move forward with the refresh. After a number of discovery sessions, user journeys, design revisions, and security surveys, I found myself staring at code I had written 8 years prior.

The Breakdown

The Good

• Codebase was well-organized
• Decent readmes for most of the project structure
• Branding in the backend

The Bad

• No documentation surrounding the build tooling
• Still running an outdated version of PHP

The Ugly

• Multisite started with good intentions, but adds layers of complications

The Beginning

With a signed contract in hand, work needed to begin. The first steps were to get a local version of the site up and running, followed by an investigation of the codebase.

Getting Started

The first step, and first challenge we encountered, was getting the project running locally. I grabbed a copy of the database and the WordPress upload folder, forked the repository to our organization, and got started. I followed my normal setup project… and nothing worked. I started poking around and remembered that the project was a multisite installation managed by the IT department.

Multisite comes with its own quirks and challenges, including some configuration tweaks and additions to the database. The other sites had been separated out into a separate install at some point, leaving the main site on its own, but still configured as a multisite.

One upside to the project was at the time we had used Github for source control and issue management, so we had a fairly complete history of the work done at the time. One downside to using git for source control is something called git blame. Blame basically shows who was responsible for any given line of code. So, it was fun to open the old project and see a lot of “blame Dave Kellam” over and over again!

Investigating the Codebase

Plank has been all-in on using built-in WordPress blocks and custom blocks in page creation for a number of years. It provides our client with a ton of flexibility, allowing them to create unique pages within a creative design system. So, it was interesting to revisit a site that pre-dated the introduction of blocks and see how we were able to achieve highly modular layouts, albeit somewhat less flexible.

This involved the creation of various custom post types that were able to be added to other posts via post pickers or short codes, to create the desired layouts. In retrospect, it is very complex and not super-intuitive, but it was the best we were able to do at the time.

Frontend

The codebase itself was relatively well-organized. The frontend assets were all located in their own folder. CSS was written using SCSS, with mixins and BEM-like syntax. That code is organized into well-named files and folders, allowing for easy discovery. The JavaScript code was implemented just prior to the advent of ES6, but followed similar patterns to the structures that emerged.

One issue we discovered was, that despite most of the project being well-documented, there were zero details about how to install and run the frontend build tooling! This in turn had led to a number of less technically inclined users installing a few different plugins that allowed snippets of JavaScript and CSS to be injected into the site.

Backend

The PHP was organized relatively well for a WordPress project. There were the minimal number of plugins that I would expect inheriting one of my old projects, but also a few functionality ones had been installed over time. One thing that wasn’t immediately discernible was the fact that a number of out-of-date. This was due to the multisite implementation. Despite having an administrator login, we weren’t able to see which plugins needed updates, as only super-admins can access the network dashboard.

The project leaned heavily into the WordPress template hierarchy, particularly the pattern of using page-slug-name for templates. This allows them to be automatically applied, but introduces fragility in the sense that the template won’t apply if the slug changes. Reusable code was chunked up into a partials folder, as well as a modules folder, which attempted to achieve something similar to blocks through the use of shortcodes.

Most of the PHP structure was how I had left it years ago. The architecture was somewhat simplified, using namespaces rather than classes to silo functions. The code was organized into well named files in the includes sub-folder, and instantiated in the functions.php file. There were also a couple additions to that functions file, which is where most tutorials tell you to stick code, and often indicates a lack of structural understanding.

Multisite Organization

The site was originally envisioned as part of a network of sites. At a certain point, a decision was made to create a riff on the main theme to use as a basic theme on the network. Given that this choice was made months into the development process, we opted to develop that core theme separately and include it in the main theme, as opposed to a parent/child theme structure. This made sense at the time, but revisiting it years later, allowed me to see it as a maintenance headache. There were times that we’d go looking for functionality in one place, but it would actually be nested deep in the core theme, in a similarly named file.

Incremental Improvements

One key thing to remember when you inherit an old project, is to not attempt changing everything at once and “modernize” the code base. Incremental change is your friend. We try to follow the mantra of “leave things better than you found them”. So, we follow our coding standards, make sure output is escaped, separate concerts, and generally try to avoid any sweeping changes to the codebase.

For example, the site is still running a slightly outdated version of PHP. That version is still supported by WordPress and the host, so it’s not the end of the world. It has been on our radar, and any new code we’ve written has been up-to-date. We have found at least one template using outdated functionality that will need to be updated, but haven’t had a chance to do a full audit to ensure nothing else would break.

Another example of incremental change was adding a new JavaScript build pipeline. Rather than rip out the old build-tooling and risk breaking something we weren’t focused on, we left it as is, and created a second pipeline that can run in parallel. The old build tooling is configured via grunt, and served to compile, concatenate and compress the sass and javascript files. We added in our baseline webpack tooling, allowing our frontend developers to write ES6+ style code, which we could enqueue with React on a per template basis.

Alongside the updates to the JavaScript buildtooling, we updated the API implementation. The original site was powered by a bespoke API which predated the REST API included in WordPress core. The original API was similar, but had a more complex rewrite structure and wasn’t easily versioned. We didn’t want to completely refactor the existing API, on the off chance that it was powering something within the college, like a kiosk, that we weren’t aware of. We created new versioned REST API endpoints to power the React drive program page index. 

Final Thoughts

It’s always interesting to inherit someone else’s project and codebase, but it’s not everyday that you get to revisit your own. Inheriting old code/projects isn’t necessarily a bad thing, and can provide learning opportunities.

I can say that I was pleasantly surprised overall. Over the years, I’ve said something along the lines of, “if you don’t hate the code you wrote six months ago, you’re not learning and evolving” to people. I won’t say that I’m wrong, but there’s definitely room for nuance. I didn’t hate my work.

Would tests have made things better? It’s debatable. It would have allowed us to ensure things weren’t breaking, but like everything else those tests would probably not have been updated in six or seven years. The project suffered somewhat from an overall lack of upkeep.

Overall, myself and the team I worked with, did a decent job with the tools and patterns available at the time. While the project isn’t the most modern, it will chug along for at least another year or two before a full redesign can be realized. That means the project will have had a lifespan of at least a decade, which is not bad for a website!

In closing, it’s worth reiterating that all of this happened because the client found my name in the codebase. When your relationship with a client comes to a close, make sure that everything is documented to the best of your abilities, and include the names of people that worked on the project. You never know if the project is a boomerang that might come back to you.