Untangling Wordpress Spaghetti: a tale about technical debt
Tags: wordpress, bootstrap, buddyboss, performance
Published: 2023-06-28 12:08:59

If I had a dollar for every Wordpress codebase I touch that’s bogged down with bad coding practices, I'd be a millionaire by now. This isn't surprising in this gig - Wordpress has a pretty bad rep for having crappy codebases, which is why it carries the stigma of poor developer experience.

This reputation isn't exactly the fault of Automattic, the creators of Wordpress. Wordpress is actually a pretty powerful CMS used by a lot of websites - one which powers 65.2% of all websites in the internet that uses content management systems. But why does Wordpress get this type of hate from the tech community?

The reason is the low barrier of entry in using the framework. Wordpress is one of the earliest CMSes to have gained adoption from the masses, which not only explains its market share but also why bad Wordpress practices are so common.

One of my recent tasks as a Wordpress developer is to solely handle the migration of a large events website from BuddyBoss into Bootstrap. For the non-technical: BuddyBoss is a course & community-focused Wordpress theme, while Bootstrap is the most popular HTML, CSS, and JS library. It's a task that I've put off for some time because of the amount of technical debt in the said website. It has been passed over from the original revamp proposal to three different developers/agencies, and me as a sole developer being the fourth entity in this human (web developer) centipede.

When I first saw the codebase of this website, it's like tracing history through code - first, I saw the poor programming decisions made by the first programmer (which was outsourced to a digital agency). They revamped the website during the time when Wordpress websites were transitioning into Gutenberg. The developers used native Wordpress blocks to replicate the old design, but they did not use Gutenberg properly and resorted to using class-based CSS to implement the styles - which is basically how you get Gutenberg salmonella… because you're eating it raw. 

In the block-based style of Gutenberg editor, the designs should not rely on hardcoded CSS classes, but in using the correct blocks which would make editing easy for the Wordpress end-user. However, because of how developer #1 implemented it, the editors then had to copy each block, with the design component relying into which CSS class(es) are assigned into the block that they copied. Gutenberg was supposed to be Auttomatic's ultimate solution in the longstanding battle of Wordpress visual editors - but this approach butchers that use case.  Unfortunately, this is the path that they took (and in describing their process I am proud to coin the term "Gutenberg salmonella").

After the agency was finished with the unfortunate revamp, the website was handed over to an intermediate Wordpress developer. Or rather, a developer who heavily relies on plugins but is not that good on customizing them if needed. Don't get me wrong, this approach is perfectly acceptable for the usual Wordpress brochure sites... but not for a website that creates multiple event pages on the daily, and used by dozens of editors from different teams around the world. Because of the need to improve editor capabilities across the site, developer #2 installed several different Gutenberg block editor plugins that would cover every use case possible - but also inevitably heavily overlaps with one another. What happened afterwards is a perfect example of why it isn't good to offer too many choices: with all the block choices they have, the editors went crazy and each used different blocks based on preference - which resulted to a lot of design inconsistencies across the website.

Developer #2 somehow made it possible for editors to insert text/tabs/images in the pre-defined way these plugins offer, but when more advanced features are needed, they had to hand over the website to more capable hands. Enter developer #3.. a seasoned PHP developer with proven experience under their belt. Were they able to deliver the advanced features that were needed? Yes. But PHP best practices do not necessarily equate to Wordpress best practices (unless you're using an object-oriented Wordpress theme like Sage). Developer #3 introduced object-oriented programming to the site's current implementation of BuddyBoss, which added a working but slightly confusing (almost unnecessary) complexity to the codebase. They were successful in adding advanced features to the site, but were apathetic to the worsening situation of the technical debt that the everyday user (editors) of the website suffers from.

And now, myself, the one who is destined to finish (and has recently put an end) to this train wreck of bad Wordpress design decisions...

This post has reached almost 800 words - I'll continue the planning and execution part on another post.