Mastering the Art of Debugging
A Developer’s Guide
Hello, dear readers! As we edge closer to unveiling our latest feature, anticipation and excitement fill the air. However, before we step into the future, it’s crucial to look back and strengthen our foundation. The December launch, while successful, introduced a few unexpected guests into our system — bugs. Today, I want to share some insights and tips on fixing bugs, drawing from my recent experiences.
1. Keep Good Documentation by Adding Code Comments
Think about your stock investment; you always want to buy stocks at the cheapest time, right? The same idea applies here: write down the documentation in the “cheapest” time, making it the best investment you can make in your project.
Tackling bugs forced me into the depths of some of the most gnarled parts of my codebase — text layout and rendering. It’s been a while since I last navigated these intricate corridors of logic and function calls. The challenge wasn’t just about fixing bugs; it was about reconnecting with my own code.
One invaluable lesson from delving back into the complexities of text layout rendering is the importance of keeping good documentation in the code comments. The process of positioning each letter onto the canvas, calculating kerning and ascender height, and adjusting the offsetY to ensure the text baseline remains consistent involves a significant amount of intricate mathematics. When this knowledge is fresh in my mind, documenting it seems like a task that can always be pushed to later.
However, it’s expensive, both in time and mental energy, to dive back into code and retrace your steps without a clear guide. On the flip side, documenting your logic and decisions when you’ve just figured them out is relatively inexpensive. You’re already there, in the thick of it, with a clear understanding of how and why everything works. Writing it down right there and then is truly the most efficient and effective way to spend your time. It will ensure the future you — or anyone else who works on the code — can quickly get up to speed.
So, my first piece of advice is this: while the knowledge is fresh in your brain, take the time to write it down. Think about your stock investment; you always want to buy stocks at the cheapest time, right? The same idea applies here: write down the documentation in the “cheapest” time, making it the best investment you can make in your project. It will pay dividends to you just like a good stock investment would.
2. Get a Good Grasp of the Libraries You Rely On
The second piece of advice I can offer is about the importance of truly understanding the libraries your project depends on. For my application, the layout engine’s foundation rests on paper.js and fontkit.js. However, a significant challenge presented itself in the form of documentation — or, more accurately, the lack thereof.
fontkit.js, for instance, offers little more than a README file on GitHub. Paper.js is better, with a dedicated documentation site, but it lacks a crucial feature: search functionality.
I undertook a considerable time investment to create useful documentation for these two JavaScript libraries. My first initiative was to organize the API reference within a Notion workspace, leveraging its built-in search function. I later migrated this organized knowledge base to a dedicated API page, not just equipped with a search feature but also integrated with an ‘Ask AI’ function, available at paperjs.typogram.co and fontkit.typogram.co. This evolution of the documentation has not only streamlined my workflow but also enhanced the accessibility of paper.js for others facing similar challenges. I also did similar work and up-streamed it for samsa-core.js available on GitHub.
Perhaps one of the most tangible benefits of this endeavor has been the ‘Ask AI’ function. This innovative feature has been invaluable, saving me time that would otherwise have been spent sifting through documentation. For those interested, I’ve penned an article detailing the journey behind the creation of fontkit.typogram.co, which you can read here.
The lesson here: the time investment in truly mastering the libraries your project relies on is invaluable. For any developer facing the daunting task of navigating poorly documented or complex libraries, I encourage you to consider the long-term benefits of investing in this deep dive, and if possible, publish and even up-stream your documentation to the original creator.
3. Beyond console.log: The Power of Step-by-Step Debugger
It’s easy to rely on the simplicity and familiarity of console.log. While this tool can provide snapshots of what’s happening within your code, it often falls short of offering the comprehensive insight needed. This is where the true power of using the step-by-step debugger comes into play, allowing you to execute your code line by line and witness the intricate dance of logic and data unfold in real time.
There is a common hurdle with paper.js: the canvas only refreshes after the completion of the entire code block, leaving you without a visual cue of the interim states your code produces. The solution, adding this line of code:
paper.view.update()Invoking this command forces the canvas to update, revealing the in-between states. It allowed me to see, in real-time, how each line of code influenced the positioning, kerning, and overall appearance of text on the canvas. Here’s a closer look at how the text layout unfolds in Typogram, step by step:
As I continue to refine and improve Typogram, I am reminded of the importance of sharing these insights with you. The journey is as much about the destination as the lessons learned along the way. Stay tuned for the upcoming updates to Typogram — we’re working hard to make it more powerful, intuitive, and user-friendly than ever before. Your support and feedback are what drive us to keep pushing the boundaries of what our software can do.
Thank you for joining me on this journey. The best is yet to come!
❧
See you next week! If you have friends interested in founding startups, please share my newsletter with them!