I’ve been a professional software developer for ten years. I have picked up on a few things which I thought I’d share.

People skills

The most important skill in software development has nothing to do with the code itself. It has to do with how you treat other people.

This touches everything from the type of comments in a pull request, to whether individuals are faulted for mistakes instead of addressing systemic issues, to a sense of safety to ask questions, to being able to listen to other people’s input, to making sure remote employees don’t feel left out, to how you deal with assholes and sexual harassment.

Never badmouth others

Never badmouth people on your team. Never badmouth people on other teams. Never badmouth other teams. You are all on the same side, trying to give the best product to the client.

Don’t do overtime

Except on rare occasions. The most important thing in your life is your health and the time you spend with those you love. Those things are fragile. Don’t take them for granted.

Interview interviewers

Interviews go both ways. You want to make sure the company is a good fit for you too, not just the other way around. What’s the percentage of women in technical positions? What do they use for testing? How do they do CI?

Welcome discomfort

Whatever you know now will become obsolete at a rate that is faster than any other science. Entire stacks change in years. If you want to stay competitive in this job market, you will need to constantly be uncomfortable and learn something new. Play with the stacks used at young and popular start-ups.

It’s legacy from the start

Every project you work on will become legacy. Legacy apps often require old tool-chains and are difficult to maintain. This is preventable to a point. I’ve found it helpful to view projects from their inception onward as legacy and keeping tabs on how hard it would be to modernize.

I’m a big fan of simple, independent, applications with well-defined interfaces. I’m also a fan of avoiding reinventing the wheel.  You want to go with the simplest design with a focus on making it refactorable. Following the advice of books like Clean Code by Robert Martin help tremendously. Prize unremarkable code.

Technical debt accrues at a pace that is hard to notice day to day. Take metrics to make that more evident, such as line of code per source file limits (with flexibility) and architectural reviews oriented towards cognitive simplicity.

Old isn’t always worse

There’s a tendency to want to refactor projects to adopt the latest language, framework, hardware, etc. While it’s important to stay current, it’s equally important to grasp of the benefits of the established tech. Adopting the latest isn’t always the greatest depending on the needs of the project.

Everything as code

There should be no manual steps anywhere to get from code to deployment in prod. Your server and networking infrastructure should be code. Your tests should be code. Your embedded environment build process should be code. If you need to follow a guide that involves following a series of steps: that should be automated. Deterministic all the way.

Check your assumptions

You will make assumptions for every line of code you write. That’s okay, but it’s also important to sometimes step back and ask yourself if this is an assumption that needs validation.

If users can, they will

If users can do a thing, they will do the thing. It doesn’t matter if it doesn’t make sense to you to do that. So if you don’t want them to do it, put that in code. This extends to APIs as well.

Use the tools

For new developers, learn to use the tools that you hear about. Use an IDE. Use a debugger and learn to set breakpoints. Use a code versioning tool like Git. Implement unit tests. Learn about contemporary software methodologies like Agile and what problems they address. If you’re new, the benefits of these things will likely seem elusive to you and you’re liable to believe that they’re more pain than they’re worth. So trust my words: it’s worth it.

Today I’m proud to show off a short work of interactive fiction that I wrote, about being trans in Ottawa. You can play through the story by clicking here.

In the rest of this post, I’ll talk a bit about the process behind the creation of this game.

Four Stages

From the outset, I realized that I wanted to create my own interactive fiction engine, that is to say, my own tools to create works interactive fiction. I did this because I thought it would be quicker to write my own than learning to become proficient in someone else’s, and because I had the ultimate goal of making the works I produced available online. I thought it would be easier to accomplish the latter if I didn’t have to work with someone else’s tools.

This would be the second interactive fiction engine I created. I used lessons I learned from my first go at it, Story Creator. Story Creator was designed to be easy to learn, but wasn’t scalable – writing longer and more complex stories became unmanageable.

If I wanted to create this work, I needed to follow four steps:

1. Design a scripting language with which to create stories.
2. Put together an interactive fiction engine that could turn those stories into playable games.
3. Create a tool that would use the interactive fiction engine, and create a website through which people could play the game.
4. Write the work of interactive fiction I had intended.

Creating the Scripting Language

I set out to create a scripting language – a way to formulate stories that a computer could understand as to make playable experiences. I spent a week or two writing tidbits of code on paper, imagining how a story could be written. This was a really fun challenge for me.

I realised that these stories, much like computer programs, could be boiled down into two fundamental ingredients: state machines and the means to move between them.

Everything in a story can be reduced to a state. The location of a player (bottom left) or a conversation with a character in the story (bottom right).

In the case of a work of interactive fiction, each state can have text associated with it. If the player is in a bedroom, then there can be text specific to that, talking about the bed and so forth. If the player is in a different location, say, a washroom, the text can be different, talking about the sink and tub.

The other fundamental ingredient, actions, change the state of these state machines. These actions can have different names depending on the state machine. For changing the location, the action could be called walking. For navigating a conversation tree it could be called speaking. The name is irrelevant. They all do the same thing: change state machines from one value to another.

With that in mind, I separated the scripting of these stories into two: entities which would contain the state machines, and actions to change their state. The state machines would be defined using a graph description language called dot.

In them, only the states of a state machine would be defined and how the states went from one to another.

graph location {

    subgraph house {
        bedroom -- upstairsHallway -- bathroom
        stairs -- upstairsHallway -- masterBedroom
        livingRoom -- entrance -- stairs
        entrance -- kitchen -- livingRoom
    }

    shed -- lawn -- entrance
    lawn -- street
}

For the text to display with each state, I used a lightweight markup language called Markdown.

# location

## house

### bedroom

You are in the bedroom. It hasn't changed since your childhood. Your pink
bed sheets. The blue walls. Your plush animals. Your polly pocket and
transformers lining the shelves. Traces of your teenage self - the boxes
of video games you kept perfectly. The computer you built, and rebuilt.
An entire life that suddenly stops midway through university.

### bathroom

You are in the bathroom.

### entrance

You are at the entrance.

Then for anything else related to the state machine, such as what initial state the state machine should be in, and what actions apply to the state machine, YAML was used.

location:
  value: bedroom
  actions: [walk]

Actions were also written in YAML. The idea was to trigger a change in state, to a specified value, by pattern matching against the sentences written by a player.

action: change
templates:
  - walk to the @value
  - walk to @value
  - walk the @value
  - walk @value
synonyms:
  walk:
    - travel
    - go
    - head
    - enter

The scripting language I designed on paper only received minor alterations during the implementation.

Writing the Engine

Writing the engine took place over the course of many months; I wrote about my efforts here when I was done. The task was broken into four parts:

• The first was creating a compiler which would take works of interactive fiction written in the scripting language defined earlier and turn it into state machines it could use.
• The second part was creating an engine which took the state machines and changed their state according to what the player wrote to advance the story.
• The third was creating a command-line tool that could act as a front-end for the compiler and engine.
• The fourth was documenting everything including how to write stories and all the parts of the engine. There’s no way I’d remember all the details in six months.

In reality, all parts took place more or less simultaneously. I put together short works of interactive fiction, which I would pass through the compiler/engine using the command-line tool to test.

I was very pleased with the end result. You could write simple sentences, and the engine would understand it, or present alternatives that it thought it understood.

Writing the Web Tool

Command-lines like that above were very convenient to me, as a software developer who enjoys retro experiences, but inaccessible to most people. If I wanted to create something other people could experience, I needed to put it online, and I needed to remove the part where people could write sentences in plain English. I created a tool that made websites for the interactive fiction, so that the only thing someone needed to play them was a web browser.

This portion only took a week to do. The majority of the work had already been done when I created the engine. Meanwhile creating simple dynamic websites was easy with React, Bootstrap and Gulp. I wrote the code to combine the two.

Creating the Interactive Fiction

With tools in hand, I set out to create the work of interactive fiction. I had wanted to do a story about being trans in Ottawa. I wanted to show how transphobia was embedded in the everyday – whether walking down a sidewalk, going into a shop, reading a newspaper or using the washroom. I also wanted to show other aspects, including queer spaces and friendships.

The story I ended up doing was about a life in a day in Ottawa. The protagonist starts off in their apartment bedroom, and is able to explore the city. Main Ottawa streets like Bank, Somerset, Wellington, Rideau, King Edward, etc. are here. So too are places like the Byward Market, shopping center, etc. The player is tasked with three objectives: get a coffee, go for a laser hair removal session, and attend a potluck.

I’m very pleased with the final product. Though most of the content will go unread by a casual player, there are many random events, four characters that can be conversed with, and perhaps a slightly different view of the city.

Feel free to give it a go yourself! The playable story is found here.

The code for the story, in the scripting language I created, is found here.

I got my first taste of 3D printing!

I had been exposed to it five years ago when 3D printers started to get into the consumer market. The geophysics company I worked for had a 3D printer in one of its offices to test out manufacturing replacement parts, including tail fins.

Fast forward a few years and 3D printing has entered the consumer market for hobbyists. The Ottawa Public Library has a 3D printer. A number of my coworkers at my current employer have one too.

So for (a very belated) Christmas gift, I was asked for a map of Vancouver to figure out the best bicycle routes. This is actually a pretty complicated problem. Rudimentary car navigation relies on cost equations along lines (roads). These lines have different weight based on their individual speed limit, so that highways are prioritized over side roads. Then you figure out the shortest path, following the lines (roads), from one point to another keeping those weights in mind.

With bicycles, you have to give paths weight according to the energy required to go up hills. This means combining two classes of data: vector (think lines like roads) with raster (think images like elevation). Open-source tools are pretty awful at combining these two. The math is fun, but difficult to implement and I don’t think the end-result would be useful. There are so many things you can do that wouldn’t be taken into account.

So I thought of an alternative: what if they had a 3D printed topographical map of Vancouver? Then they could see for themselves what routes might be better for them. Our brains are pretty great computers.

Making the model

The first step was to download elevation data of Vancouver. Vancouver, like many other cities, releases this data for free as part of an open data initiative. This was likely collected through aerial surveys using LIDAR, post-processed to remove buildings and make the topography evident.

I downloaded the data and loaded it into QGis, an open-source GIS software. I also downloaded road data and bicycle routes from Vancouver’s open data website. The person this was for had also given me important locations to them, which I loaded in as point data (not shown in these screenshots for privacy).

I then used a plug-in for QGis, called DEMto3D, to create a 3D mesh in the STL format commonly used by 3D printers. I loaded this mesh into a free tool called Autodesk Meshmixer, as to simplify the mesh. The mesh file was initially 250 MB, and the 3D printer I was using supported a maximum of 64 MB.

I then printed the mesh. The end result was pretty great! I lost some of the detail in the original mesh, which showed the road as bumps.

I was very pleased with the end result!

In a previous blog post, I announced the completion of an open-source text adventure game engine, aptly called Adventure.

The game engine came with a command-line front-end for demonstration purposes.

I’ve now implemented a quick-and-dirty web front-end of the engine. It also includes text-to-speech, reading out the contents of the story to the user. I had intended to implement speech recognition as well, but this isn’t enabled in Firefox by default so I didn’t include it.

Unlike the engine, this front-end is not really put together with other developers in mind, but if you’re interested, you can get the code here. It’s pretty simple stuff; the UI is made with React, gulp is the task runner putting everything together, and I use Express as a web server.

Next up is writing a work of interactive fiction.