Thoughts on Debuggability

In the early days of web browsers, there were no developer tools. From Netscape to Internet Explorer, and the first version of Firefox, if something wasn’t aligning properly or your JavaScript wasn’t behaving as expected, there was little you could do. The browser provided no additional information.

Everything changed with the arrival of Firebug, the first real developer tool for web applications. As a Firefox plugin, it exposed the inner workings of a web browser to software engineers. Firebug set the stage for native browser developer tools and inspired frameworks, servers, and more to create their own developer tools. It also underscored a new critical aspect of web application development: debuggability.

Debuggable code not only performs its intended functions but also allows you to inspect its actions to identify the source of problems. When code isn't debuggable, issues are opaque, hard to diagnose, and consume a lot of time. This was the case with the old ESLint configuration system, eslintrc.

While the eslintrc system had served us well for a decade, it had become a growing maintenance burden. The developers who implemented many of the newer features were no longer on the team, leaving the remaining team members struggling to address the increasing error reports. We spent a significant amount of time investigating whether issues were bugs or misconfigurations, and the volume of requests continued to grow. This ultimately led to the creation of a new configuration system, called flat config.

The flat config system, as the name suggests, represents the entire configuration in a one-dimensional array. It loads a single configuration file instead of merging multiple files as eslintrc did. This simplification makes the new configuration system much more debuggable. Additionally, we developed a tool called Config Inspector to help developers understand their configuration files. Even the ESLint team relies on Config Inspector for debugging configuration issues.

Some of the things that make code debuggable include:

• Descriptive errors - Errors should contain as much information as possible to pinpoint the source. Replace common unexpected errors with intentional ones that provide the necessary information.
• Descriptive logging - Logging the actions of the code helps track down problems. Logs can be output to a console, saved in a file, or fed into an analysis system. (In ESLint, --debug shows the log.)
• Modularity - Encapsulate functionality so that individual components can be tested separately, making it easier to isolate problems.

Whenever you design a feature or system, it's worth investing extra time to make it debuggable. Asking, “When this fails, how will I figure out the problem?” now will save you and your team significant time later.

Key Takeaways

• Developer tools are an important part of today’s software development process. It’s worth the effort to make your code work with them, create your own, or at least have a debugging experience.
• Code is more debuggable when you use descriptive errors, descriptive logging, and modularity.
• Taking extra time to ensure new code is debuggable upfront will pay off down the line with a lower maintenance burden..

Understanding JavaScript Promises I just updated my e-book, Understanding JavaScript Promises, for 2024! It now includes information about Promise.withResolvers() and a whole new chapter on using and creating abortable functions. Buy the E-book

Stuff I've Enjoyed this Month

🎬 Prioritizing Technical Debt as if Time and Money Matters by Adam Torhill (GOTO Conferences)
This talk from five years ago is one of the best deep-dives into technical debt I've ever seen. Torhill goes into the coding patterns that can be considered technical debt and how to address them.

📖 An Introduction to Coaching Skills by Christian Van Nieuwerburgh
I've had my coaching program for nearly five years now, and I'm always looking to improve my skills. This book is written for beginners yet is full of practical advice even for coaching veterans. Highly recommended if you're in any leadership or coaching position.

📝Epic Programming Principles by Kent C. Dodds
I've never seen such a complete documentation of one's programming principles as this. Dodds goes into all aspects of programming including core philosophy, testing, debugging, career, and more. Well worth a read.

🎬 Custom dropdowns just got a whole lot easier (finally!) by Wes Bos
The ability to customize the appearance of <select> elements has long been desired by web developers. Finally, we have that ability, and this video shows how to do it with HTML and CSS.

📝Add browser speech input & output to your app by Pamela Fox
New browser APIs are popping up at a rapid pace and I had no idea that speech recognition and generation were now available. This post walks through how to use these new APIs to speech-enable your app without the need for cloud-based services.

🎬 Understanding the V8 JavaScript Engine by Lydia Hallie (freeCodeCamp talks)
This video walks you through the internals of the V8 JavaScript engine, the engine powering Chromium, Node.js, and Deno. It's fairly short at 10 minutes yet somehow manages to squeeze in good explanations all of the key aspects of V8.

📖 Leading Effective Engineering Teams by Addy Osmani
This book is targeted at managers who oversee engineering teams and is full of good advice lifted from Osmani's 10 years at Google. Each chapter goes into detail on a different topic and provides numerous tools and advice for all kinds of situations. Even if you're an individual contributor, you'll still learn a lot from this book.

What I'm Working On

🏠 Real Estate: Another issue at a property ended up costing me a lot of money. The dryer broke, so I opted to buy a new one. Unfortunately, the new one wouldn't mount onto the old washer, and because there is no place else to put these appliances, I ended up needing to buy a new washer too. Follow my Instagram for real estate photos.

💻 Open Source: I updated Crosspost, my utility and CLI for posting messages across different social media networks at the same time. I improved the API to make it possible to post to the same social network multiple times with different credentials and also cleaned up the CLI output.

💻 ESLint: The two things I've been spending time on are:

• A rule for the CSS language plugin that validates against baseline.
• An RFC to add back "extends" to ESLint configuration files.