---
title: #4 - Refactoring A False Sense of Simplicity
published: false
date: 2025-09-12 01:08:54 UTC
tags: refactoring,WebDevelopment,FrontendDevelopment,CSS
canonical_url: https://campfire.dlseitz.dev/4-refactoring-a-false-sense-of-simplicity
header:
    image: '/assets/20250911_2016_Coding by Campfire_simple_compose_01k4xqta8sfjyrws9ezcwjpg9x.png'
    attribution: 'Image generated with Sora. | © 2025 Derek L. Seitz'
---

Hey everyone! Welcome back to [_Campfire Logs: The Art of Trial & Error_](https://campfire.dlseitz.dev). In my last log, [**_#3 - Data Privacy: Things to Consider_**](https://hashnode.com/post/cmf3futzv000102l4hgh339fv) **_,_** I walked you through how I developed the privacy policy for my website and discussed some of the considerations that developers should make when handling client data. Today, I want to get back to the technical side of things by discussing the [refactor](https://daedtech.com/refactoring-development-technique-not-project/#:~:text=Code%20refactoring%20is%20the%20process%20of%20restructuring%20existing%20computer%20code%20%E2%80%93%20changing%20the%20factoring%20%E2%80%93%20without%20changing%20its%20external%20behavior.), or restructuring of existing code, I recently did on a demo website, including the things I learned along the way.

## The Original Demo

About a year ago, I designed and built a demo [static](https://kinsta.com/knowledgebase/what-is-a-static-website/) eCommerce website for a web development course in college. The requirements werent anything crazy:

- choose a scenario from the provided list

- create four distinct HTML pages

- use a single, external CSS stylesheet

- use JavaScript to create a couple of modals, a shopping cart, and a contact form

Easy enough.

But with this having been my first web site, and not really having anybody to tell me when to put on the brakes with the creativity (it was an online course), it was the perfect way to trigger a bipolar manic episode. Some may say I went a tad overboard on the project (hence the little menty b or two that came along with it), and I wouldnt disagree with them.

While this project, in part, [acted as a catalyst for me to resume seeing my therapist](https://www.techuk.org/resource/addressing-mental-health-in-the-tech-industry.html), I have to give it props for firing up my interest in web development (sounds contradictory, but its true). When I came out on the other side of it, I finally realized Hey! I can actually do this!

So what exactly was the problem with the demo?

## The Problem

The problem with the demo was this: due to the curriculum requirements for the project, along with the fact that it was meant to be an intro-level website, the focus on best practices was more about basic fundamentals than that of the full development lifecycle. [Maintainability, scalability, and the potential for future enhancements](https://www.einfochips.com/blog/importance-of-adopting-best-practices-for-scalable-and-maintainable-systems/) werent considerations during the build. In other words, my codebase became a [tightly-coupled](https://cleancommit.io/blog/whats-the-difference-between-tight-and-loose-coupling/), [monolithic](https://www.ibm.com/think/topics/monolithic-architecture#:~:text=Monolithic%20architecture%20is%20a%20traditional%20software%20development%20model%20in%20which%20a%20single%20codebase%20executes%20multiple%20business%20functions.) behemoth that wasnt easy to read or work with, no matter how well-commented it was. I didnt understand it enough at the time, but just like with backend development, having a [loosely-coupled](https://cleancommit.io/blog/whats-the-difference-between-tight-and-loose-coupling/), [modular](https://www.institutedata.com/us/blog/modularity-in-software-engineering/#:~:text=Modularity%20in%20software%20engineering%20refers%20to%20the%20design%20approach%20that%20emphasizes%20the%20separation%20of%20concerns%2C%20where%20a%20complex%20software%20system%20is%20divided%20into%20smaller%2C%20loosely%20coupled%20modules.) front end should always be the goal.

On top of that, I tried my best to take an accessibility-first approach. At the time, I understood the importance of semantic HTML, but I didnt quite grasp that [ARIA attributes](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) were meant for filling in gaps for [assistive technology (AT)](https://www.atia.org/home/at-resources/what-is-at/) like screen-readers _when using HTML tags without inherent semantic meaning._ This led me to over-apply attributes such as ARIA-label and ARIA-labelledby, which really cluttered up my code. But hey, A for effort, right? Ill talk about this more a little later.

Now, it really isnt uncommon for either of these to be overlooked in foundational academic settings. After all, the focus is often on making the code work more so than perfect execution. But that isnt quite the case for professional-grade work (what Im aiming for). So a few weeks ago, I decided what better way to continue practicing professional development standards than to refactor this demo. I may have slightly underestimated what I had coming

## Challenging the Notion of Simplicity

I used to associate simple programs or simple design with having as few files or components as possible. In my early days of coding (not quite the same thing as developing), I thought that meant if an application was contained to a single file, it meant that it was a single object. While in some ways, this isnt necessarily incorrect, I didnt yet understand how I was looking at it from a very abstracted or zoomed-out point of view.

I learned, however, to think about the design and architecture of software as a system of interconnected parts. Its much like the human body with its many systems (immune, digestive, etc.) all working together to function as a whole. This helped me to better understand development practices like the [separation of concerns (SoC)](https://www.geeksforgeeks.org/software-engineering/separation-of-concerns-soc/) and writing [DRY (Dont Repeat Yourself)](https://www.digitalocean.com/community/tutorials/what-is-dry-development) code.

With these things in mind, I came up with the idea to refactor the demo, because how hard could it possibly be?

### The Monolith-to-Module Challenge

One of the hardest parts about revisiting old code is trying to make sense of what its actually doing. You can do an excellent job of commenting each section of code and still end up spending a good amount of time scratching your head while trying to figure out what it all meansand that isnt necessarily a bad thing.

As I got started on this refactor, I really thought the head-scratching meant that I didnt know as much about web development as I believed I did. However, after finding several snippets of code that could have been better written another way, it didnt take very long for me to realize this wasnt the case. The initial confusion actually signaled I had a deeper understanding and that my approach to development had evolvedvery much a good thing, right? I had to think back to that first-time mentality from a year ago so that I could decipher what I had intended the code to do, then translate that functionality into a cleaner implementation.

Modularizing the HTML files was the easiest part of this whole process, at least for me. As Ive mentioned before in some of the other _Campfire Logs_, I use [11ty (Eleventy)](https://11ty.dev), a [static site generator (SSG)](https://www.cloudflare.com/learning/performance/static-site-generator/), along with the templating language [Nunjucks](https://github.com/mozilla/nunjucks), to write modular, easier to maintain static websites. It was a breeze breaking the HTML into smaller, reusable components to be injected into a base template of boilerplate HTML using Nunjucks conditional logic (for-loops and if-statements written in Nunjucks syntax). Sure, this broke up four HTML files into several other files, but this didnt make the project more complex, just more organized and DRY.

### The Cascading Nature of CSS

As I moved on from the HTML-turned-template files, the next logical step was to break up the incredibly long CSS stylesheet. Now remember, per the course projects requirements, I had to use a single stylesheet for all CSS rules. Because of this, the original `styles.css` file ended up being 1158 lines long. Fortunately, I had grouped rules by the page to which they applied using comments (`/* <comment> */`), and those comments created natural breakpoints when separating the rules into separate stylesheets.

That sounds like it made this part incredibly easy as well, but it wasnt nearly as easy as youd imagine. I didnt do the best job at keeping all style rules within their corresponding sections, so once I linked the page-specific stylesheets into the front matter of the corresponding page template and the global stylesheets (for components like the header and footer) into the base layout template, the styling across several pages broke completely.

Great! Were having so much fun here! But in all actuality, I needed this. Why, you ask? Well lets look at an example of the `<head>` section of an HTML document, and Ill explain:

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1757634763445/499618b7-0af6-422f-bb3e-6793004330e1.png)

In the example here, lets say it is of `contact-page.html`. We can see that the browser will first load `styles.css`, which holds the style rules that are common to every webpage on the site. Then, the browser will load `contact-page.css`, which holds the style rules that are specific only to `contact-page.html`.

The way a browser applies these stylesheets is in the order they are listed, from top to bottom. If both stylesheets contain a style rule for the same element, the rule that is listed last in the document will override the previous one. This is because the latter styles are applied after the former. The browser prioritizes the last rule it reads.

So with the layouts for most pages across the demo breaking, I realized a few things in rapid succession:

1. I did not, in fact, have my style rules as organized as I previously thought

2. Several important base rules must have been overridden somewhere in a later part of the original stylesheet because now they werent being applied as I expected them to be

3. This would require a methodical, page-by-page approach to untangling the mess I had unknowingly created

While this seems like it would be incredibly frustrating, especially after having just broken up my original `styles.css` file into several purpose-specific stylesheets, it gave me the opportunity (yes, opportunity) to systematically improve my usage of semantic HTML, reduce my overuse of accessibility-focused HTML attributes, and leverage the cascading nature of CSS to improve my design rather than trying to work around it.

### Accessibility & Semantic HTML

I think for many, the term accessibility in the context of web design and development is believed to mostly mean contrast ratios and font sizes. Thats how I thought about it, at least, until I was taught about assistive technologies like keyboard navigation, screen-readers, and speech recognition tools (among others). I knew what screen-readers were, having messed around with them on Windows, Apple, and Android devices, and I knew I could tab through objects on a web page or desktop, but I didnt understand how they worked.

Many (but not all) HTML element tags have an inherent meaning recognized by assistive technologies. This is what creates structure and logical groupings that enable these technologies to present information in a useful way to individuals using said tech. For example, screen-readers use semantic HTML tags, like `<section>`, `<form>`, hierarchal headings (`<h1>`, `<h2>`,), and others, to navigate documents and read aloud related content in a way thats more easily understandable for individuals with visual impairments.

For tags such as `<div>` and `<span>`, which have no inherent meaning, thats where you would use [ARIA attributes](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) to give them meaning and a role. But as a rule of thumb, its best to always try and use a semantic HTML tag first and foremost, and only use ARIA as a last resort. This is often referred to as the First Rule of ARIA.

When I built the demo for class, I didnt understand accessibility and semantic HTML enough. This led me to incorrectly use semantic tags and add ARIA attributes to tags that simply didnt need them. For assistive technologies, this can cause a lot of confusion in an HTML documents structure, which can lead to bad UX for those reliant on accessibility features. Having to go over the entire HTML and CSS during the refactor meant a chance to truly make the demo accessibility-focused beyond just contrast ratios and font sizes, which was important to me.

## Looking Back

Modularizing and refactoring the demo website also introduced a few minor bugs in the JavaScript that controlled the interactive components on some of the pages, but that meant I had to make sure event listeners grabbed the corrected HTML elements from the DOM. Because I thought of JS like I did Java (because its a programming language, not the similarity in their names), separating concerns into different scripts was a little more instinctual for me and was done in the original project, saving me a bit of work.

While I thought going into the refactor it would be as simple as copying/pasting code into a more modular file structure, Im really glad that I was wrong. Not only did the refactor give me the chance to go back and visit an old project (the nostalgia was real), it really boosted my self-confidence to see where I was a year ago in my development journey versus where I am now. We often dont realize just how much we grow and evolve over a period of time because we get trapped thinking about whats in front of us. As somebody that often questions his own levels of understanding, a project like refactoring an old codebase is a great way to squash feelings of inadequacy and self-doubt. Im really glad I did it.

## TL;DR

I built an intro-level website for a college course a year ago that became a tightly-coupled, monolithic behemoth. Deciding to refactor it to a more professional standard, I learned that while modularizing the HTML was a breeze, breaking up the single, 1,158-line CSS file was much harder. This "mess" provided an opportunity to go back and fix my overuse of ARIA attributes and improve the site's overall accessibility and semantics. Ultimately, the refactor was a major confidence-booster, reminding me of the growth I've made as a developer over the past year.

## Before You Go

As always, thank you so much for checking out this _Campfire Log_! Be sure to comment with your own experiences. Maybe you had a similar one to mine, or maybe yours was way different. Id love to hear about the challenges you ran into and how you got around them.

The refactored demo is now live. You can check it and its source code out by visiting [https://dlseitz.dev/demos/](https://dlseitz.dev/demos/) and clicking the corresponding button. I recommend doing so using a desktop browser simply because the demo isnt currently mobile-friendly. Making it [responsive for smaller screens](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design), as well as improving the custom alerts and shopping cart feature, is next on my list of things, however. Additional dynamic features have also been added, such as an interactive events page and a dedicated page to attributions for the royalty-free media I used, so you may be interested in seeing how some of those work.

Looking ahead to #5, Ill be talking more about those expanded features. Ill also explore what it meant to separate the presentation, data, and logic layers of the demo and how that enhanced its modularity, dynamism, and interactivity. Be sure to check back soon!