November 11 - 12. In person and online.
Catch up

We are a community of programmers producing quality software through deeper understanding.

Originally inspired by Casey Muratori's Handmade Hero, we have grown into a thriving community focused on building truly high-quality software. We're not low-level in the typical sense. Instead we realize that to write great software, you need to understand things at more than a surface level.

Modern software is a mess. The status quo needs to change. But we're optimistic that we can change it.

## Latest News

Ryan Fleury

Happy New Year, Handmade Network! I hope you all had an amazing holiday season, and I hope you're all looking forward to 2022 as much as I am.

The Handmade movement had a huge year in 2021. The Handmade Seattle conference, hosted by former Handmade Network staff member Abner Coimbre, brought the community together for yet another time, even in the face of the many changing circumstances that 2021 held in store. We on the Handmade Network staff team hosted the Wheel Reinvention Jam, and we had a number of very well-done project submissions. Ben Visness and Asaf Gartner rewrote the entire Handmade Network website backend in preparation for some huge features that are slowly making their way onto the website.

This is, of course, only an incomplete list. The real list of all of the great things that happened for the Handmade movement in 2021 is not enumerable. But let's dig into these.

Abner Coimbre successfully hosted Handmade Seattle for a 3rd year in the face of consistently changing circumstances - local regulations for COVID-19, traveling restrictions for international Handmade community members, and many other things I don't know about or understand. Handmade Seattle, in 2021, hosted 25 different presentations, all being either talks, demos of Handmade projects, or podcast episodes. The conference happened both live in-person and also virtually.

I'm not exactly sure how he manages it, but with each year, Abner has produced a better conference, in the face of COVID-19 restrictions, all while staying independent without any corporate sponsorships. I had the privilege of attending in-person, and I was amazed with how smoothly everything went.

I'm here to tell you that the media - talk recordings, demo videos, podcast episodes - from Handmade Seattle 2021 is starting to roll out, so you can enjoy all of the content from the conference for free, even if you missed it originally. To check it out, go here.

## Wheel Reinvention Jam

As I mentioned, the Handmade Network staff hosted our "Wheel Reinvention Jam" back in October. This was like a game jam, but instead of being for games, it was all about taking existing "boring" software - the kind of stuff that we regularly depend on as users, like file explorers, word processors, and more - and innovating on it. To put it shortly, the jam was a huge success, and we got a number of amazing project entries.

We on the admin team also did a stream to show off some of our favorite projects. And then, something horrible happened: I lost the recording. Long story short, I downloaded the recording, and unknowingly permanently deleted it as I was cleaning off my desktop one day. In other words, I had a very important lessons about backing up important data on my machine.

Hope was, as far as I was concerned, lost.

But I was mistaken - hope is never lost in a community with a hero protecting it.

Martins Mozeiko, the resident programming wizard in the community, has an automated system set up that records stream VODs so he can enjoy them at his own pace after they air. He had a copy of the stream's recording!!!

So, I'm here to report that - because of Martins - you all have the ability to watch the Wheel Reinvention Jam recap stream. Here it is:

## Personal Projects Update & Discord Integration

Ben and Asaf have been hard at work at the admin team's plan for projects on the Handmade Network website. We realized that the #project-showcase channel on the Discord server was so popular because so many projects didn't fit the original model of projects on Handmade Network. These projects were smaller, sometimes not intended to be finished, were experimental and not well-established, but nevertheless demonstrated very great results that people love to see. We figured that this prevalent force in the community - of those who are working on such projects - should be reflected in the services we offer on the website.

Now, Handmade Network has two tiers of projects: Personal Projects, and Featured Projects. Personal Projects can be created by anyone, and do not require approval by the admin team. They give you a place to host media for your project.

Featured Projects are similar to the old Handmade Network website projects; they are like personal projects, but are upgraded with a number of features (forums, episode guide, etc.), and they are presented as being featured (and thus hand-picked by the admin team).

The most awesome part of all this comes with how media is managed for these projects. For a while now, we've had the Community Showcase section of the website - these are posts from the #project-showcase Discord channel of people showing off work on their projects. We've upgraded this system to also allow associating some of those posts with projects (and other things) through tagging.

On each post, you can add tags: Here is a screenshot of my awesome work on &hero for the &cooljam. Each word that follows a & symbol refers to one of these tags. Each project gets one tag name, that it can use to pull in certain resources. And, other things can have tags too (like jam events), that can categorize posts in other ways.

Posts that are tagged will not only go to the regular Community Showcase section of the site, but they'll also be pulled onto their respective project pages (and, yes, a post can be tagged to multiple projects).

Ben is writing a more in-depth post about this. It'll be released shortly, so if you're looking for more details about how these new features work, you'll want to check that out when it's ready.

I am extremely excited for this new upgrade to the site's project features. Go and try it out!

## State of the Network Podcast 2021

I've just released a new podcast episode I did with community member Rudy Faile, who interviewed me about the current state of Handmade Network, all of the things in the Handmade movement in 2021, and where we are planning to go in 2022. Check it out here!

## Closing Remarks

One final remark I want to make is announcing a temporary hiatus for myself on my side-projects, including Handmade Network. In short, I'm taking at least a few months for self-improvement, to focus on some very important personal matters. Thank you to all of those who have expressed support - I'll be back at some point during this year, and I will keep my finger on the pulse of the community, because I'm so excited for what is yet to come.

That's all for the news, for now. Here's to a prosperous 2022, and let's continue moving the ball forward!

Best wishes, Ryan

## Around the Network

Evan Butterfield
Blog comment: Surgical programming
Mārtiņš Možeiko
Blog comment: Surgical programming
d7samurai
Oliver Marsh
Oliver Marsh
New blog post: Surgical programming

This post is mirrored on my blog.

I have been relatively busy lately due to unpacking all my things from my cross-country move. Some of my hobbies have been receiving more time. However, don't worry, Cakelisp and GameLib development still continues.

For this month, I'm going to write a short article about an approach I take to difficult programming tasks. I call it "surgical programming".

# The key difference between junior and mid-level software engineers

In my career, I think one of the most important skills I had to develop was learning how to read code.

My less-experienced self would frequently reach out for documentation, or only read function signatures. I would call functions other people had written without reading them myself to confirm they did what they claimed.

Now, I rarely ever read online documentation. The code is the ground truth, and additional context can be gleaned from reading the version control system logs for the file. I try to read much more functions in their entirety before using them. When I have a question about some functionality, I try to read the code before asking the original developers for help.

I think reading code is a skill that you can practice, but it definitely takes discipline. If you respect the programmer who wrote the code, it gets a bit easier.

John Carmack recommends[^1] stepping through code from main() to understand what's going on:

An exercise that I try to do every once in a while is to "step a frame" in the game, starting at some major point like common->Frame(), game->Frame(), or renderer->EndFrame(), and step into every function to try and walk the complete code coverage. This usually gets rather depressing long before you get to the end of the frame. Awareness of all the code that is actually executing is important, and it is too easy to have very large blocks of code that you just always skip over while debugging, even though they have performance and stability implications.

This is also a good way to force yourself to read the code---the instruction pointer acts as a virtual bookmark, and you can go statement-by-statement rather than having to find the best place to start in the myriad of files in a codebase.

# Surgical programming

Some tasks require a large amount of code or a complex system to be comprehended before the correct modification can be discovered and implemented. Surgical programming is a way to systematically approach these tasks.

It relates to reading code because it essentially divides hard problems into two phases: a pre-op (reading) phase, and a operation (writing) phase.

## Pre-op

The pre-operation is the first phase in approaching a difficult task. The goal of pre-op is to understand the system and the task, answer any questions you have, and define a clear implementation sequence for the operation.

Importantly, the pre-op puts you on the hook: you don't get to write code until you've read enough to complete the operation plan.

When I'm embarking on a difficult task or hairy investigation, I make notes[^2] under a "Pre-op" heading where I list everything I encounter while reading that is relevant to the operation.

I also think of things I don't know and add them as to-dos on the pre-op. I can't start writing code until I've read enough to have good answers to the to-dos. They can be questions like "how did they handle X?" or "what do I need to modify to get Y?". It also includes things like "what do designers mean by Z?" where I have to talk to concerned parties to gain more context and requirements.

It feels good to call it a pre-op because it's more cool sounding, and feels like you're still making progress and spending time wisely. It could also be called the "research phase", but in my opinion that sounds much more boring.

When trying to understand complex systems, you may need to insert logging, visualizations, or other instrumentation to help illustrate the system's behavior. This is appropriate to do in pre-op, and will likely help with future investigation, so it should be kept in the code (perhaps behind boolean toggles or #if clauses, if necessary).

The key with this technique is not starting "work" on the task until you are sure you know what to do. In my career I remember making false starts where I would write a bunch of code only to find the approach wouldn't work half-way through implementing it. In almost every case the problem was a lack of understanding of the existing code. The pre-op helps to reduce chances of false-starts, because you deliberately seek out your blind-spots in understanding a system and illuminate them.

Once all your questions are answered and you feel you have a good understanding of the situation, you can write out an operation plan. This is a step-by-step outline of the things you need to do in order to make the modification correctly. It is useful as you are reading code to take note of functions and whatnot that are going to be relevant to the operation. If you do this, you will be able to jump straight to the definitions, signatures, etc. that need to be modified.

## Operation

Once you have answered all the questions in the pre-op and have an operation plan, you can proceed with the operation.

It feels good to write the code now, because you can just blaze through it. You're no longer "feeling around" while at the same time fighting compiler errors. This happens when your code is written with only a half-baked understanding of the system you're changing.

The key during the operation is to notice when you still trip up. Could that have been handled in the pre-op instead? Did you start the operation before you were ready? You can write these instances down and form a pre-op checklist for the next time, if you find yourself consistently forgetting them.

The final part of the operation is validation. You should step through code in a debugger the first time you run it, checking all of your assumptions and confirming the data is modified as you intend. This is a great way to cut down on iteration time, because you don't waste time getting your hopes up and skipping straight to testing. Off-by-one, inverted conditionals, and error-handling are usually very obvious when stepping through code, but difficult to spot when only testing.

## Exploratory programming

There are some problems where it is necessary to make a few different attempts at implementations. This is sometimes called exploratory programming. The surgical approach would consider this style of development part of the pre-op, because it's about gaining more understanding before writing the eventually committed operation code.

These types of problems don't fit as well into the surgical method, which is okay. It's mainly important to recognize when you are flailing due to lack of understanding versus exploring in order to gain more insight. The goal of flailing is to complete the task[^3], whereas the goal of exploring is to learn new things about the system.

## Debrief

Once you have completed a task, it can be beneficial to analyze at the meta-level various things:

• How long it took to complete the task
• What things during pre-op made understanding the system difficult (software architechture, etc.)
• Why the task was required. If it was due to a bug, why did the bug occur? Could that type of bug be automatically or systematically prevented?
• How you can improve future operations

# Conclusion

Surgical programming provides a deliberate structure for approaching complex problems. It becomes automatic after you've done it for a while, but I hope especially for more junior programmers (or for anyone on very complex problems) having the explicit pre-op and operation phases will make solving hard problems easier.

[^2]: I make all my notes in Org-mode, which is simply unmatched in its suitability for complex note-taking. In this case, the nesting and folding of headings helps manage the complexity. You can also insert direct links to files and lines of code which are relevant. I also copy-paste code snippets into my notes for easier reference.

[^3]: In The Pragmatic Programmer they call this Programming by Coincidence---if your flailing ends up working, it's only by chance, not by a deliberate, systematic approach.

Simon Anciaux
Mārtiņš Možeiko
da447m
Mārtiņš Možeiko
da447m
Mārtiņš Možeiko
da447m
Mārtiņš Možeiko
Mārtiņš Možeiko
da447m
Simon Anciaux
da447m
Simon Anciaux
Evan Butterfield