This month I spent most of my time working on the writing portion of my project. My main tasks were simple: explain the intricacies of compiler design and implementation in a way that someone with no programming experience could follow along with, and also explain how my specific compiler worked to someone who does have some programming experience. I also improved my compiler a bit more, adding some quality-of-life improvements and implementing a few of the features that I wasn’t quite sure how to implement in a reasonable way in December.

        For my non-technical writing, I followed the pattern of the first two articles I made last month. My very first article was a very high level “what even is a compiler” explanation, and my second one gave an extremely high-level explanation of the entire compilation process. Specifically, it explained the process as a series of large and mostly self-contained steps in a “pipeline.” The articles I wrote this month extended upon this by actually going in-depth on each of those steps in the process, and explaining them through imaginary (though inspired-by-reality) examples with simplified languages. This went relatively smoothly, albeit with a rewrite of half of one of the articles after I realized I based my explanation on an assumption that wasn’t true. After that and some proof-reading, I had articles I was relatively happy with.

        After doing that writing, I then had to actually face the more daunting of my three tasks: documenting the big pile of code I’d written over the last two months. While I had a decent mental map of my code (I’d written it, after all), that mental map was difficult to translate into good documentation that was both easier for a programmer to read than just skimming through the code and actually explained enough to make it worth reading in the first place. I decided to start in a similar place as my non-technical articles, but instead write up how those abstract “steps” in the compilation pipeline were actually performed in my compiler. This gave me a starting point for explaining the overall architecture of my compiler, and I did my best to provide a (relatively) succinct high-level overview of exactly what my compiler did, from beginning to end. I then started focusing on the specifics of my compiler, and how I translated my programming language instead of how to translate a programming language. I spent more effort on the smaller details that are effectively irrelevant to understanding the ideas but are essential for actually making a real compiler for example, and explained the usage of industry-standard tools rather than creating simplified (imaginary) versions of those tools for the explanations in the non-technical articles.

        In addition to all of that, I did some bug-fixing on my compiler. I found and fixed a few weird bugs, found and fixed an oversight or three, found and improved some code that was just plain stupid, and implemented support for a few less-essential features of the language. This part was fairly unremarkable, just routine maintenance and improvements as I expected to be doing around this time.

        Overall, my project is on-track. I need to continue on my quest to document the dark corners of my codebase, and I need to start documenting the language itself instead of relying on the test files that I had sitting in a subfolder. I expect to be able to easily finish this by next month, but I need to find ways of better explaining some of the more complicated topics in the compiler. As of right now I have some scraps from old articles that I can repurpose, but we will see on that front. The last main job I have is to get the compiler into a more “usable” state than it is right now, and that will take a bit more work. I need to work more on flushing out the obscure bugs in the compiler, which will take time. I just need to start writing a lot of code in my language, and testing out how my compiler deals with it. Ideally, I should set up an automated tool suite that will do this for me, I just need to figure out how to actually make that work and how to hook it up to the code that I already have.