Rob Watts

The words below are part of the Wonderbly developer guide. All credit should go to Hraban Luyat. He’s an incredibly smart guy and you’ll be lucky to have him on your team.

This note is about the importance of writing code with other people in mind. Knowing that the poor sap who has to deal with your crappy code is a colleague you respect, someone you may never meet or (very likely) you.

Considering other people

What really, at its core, is programming about? What are the most common causes of friction and losses of efficiency in the programming process?

To gain some insight into this matter, make sure always to consider your coworkers. You write and contribute code not for yourself, but for your colleagues (and for your future self, who will have forgotten everything that present self knows). This includes colleagues who have not joined yet, colleagues who will join after you are gone, even after you and everyone presently working with you are gone. When all that remains is the work; how is it used, and how can it be made to optimally speak for itself?

All our dogma, every rule we have, all of it attempts to optimise for that scenario. That is where, we believe, the most fundamental gains in efficiency (and morale) can be achieved. This point of view underpins our entire methodology, and should be kept in mind when reading this document.

Great code is easily understood

The most important job that code has is: to be understood by your colleagues, both present and future.

Fulfilling its intended purpose correctly (aka “working without bugs”) is number 2; because understood, broken code can be fixed; but working, misunderstood code will break and then cannot be fixed.

In order to understand code, a programmer (your colleague, or future you) will navigate the code using those two perspectives. They tend to go through these phases, in order:

1. Read the least amount of actual code to get a vague idea of how it works, change the minimal amount of code to achieve their task, ignore everything else. Don’t read comments, don’t read docs, don’t read unrelated code.
2. If this doesn’t work: attempt to read some comments close to the code they think is relevant, maybe some related function definitions and types, some calling code.
3. Nightmare: the task still can’t be completed. Curse whoever wrote this spaghetti, a pox on who hired this tool. I am relegated to reading documentation, ugh. This troglodyte was apparently not aware of the maxim “good code is self documenting”.
4. I need to see who this idiot was. I have to see their face. Who could be this obtuse. What absolute waste of oxygen produced this nightmare. git blame. Oh, it was me 6 months ago.

Point being: people only open a project when they have a specific job to do. That task is their only priority, and they will (want to) spend the absolute minimum amount of mental energy learning about any idiosyncrasies of this project. Nobody will open this project just because. Nobody will know, nor care, about the conventions, about the unwritten rules, or even the rules written in bold letters in the README. Don’t get frustrated by this: it is wasted energy. Rather, accept it as true, and write code that is resilient to it.

Great code is easily understood. Above all else. It can be understood using those two dimensions: the code & comments themselves (1), and sometimes, in the extreme, the history of how it came to be (2).

Be demanding now to avoid burdening the future

As developers, we need to think of the code we write as our personal product with our fellow developers as customers. The reverse is also true, we must act as demanding customers when presented with our fellow developers code.

New code must be maintained, likely by developers who the submitter or reviewer will never meet. For that reason we must be mindful of burdening future developers with changes we make now.20

This note outlines a simple process for managing a backlog of work. It is basically a slimmed down version of Scrum. Or a mildly pimped up version of Kanban.

Who this is for

This process is best for small, multi-disciplinary teams who need a better way to manage their work. They probably have none to little existing process, like simple lists or shared documents. External folks are usually chucking in requests that are mounting up in a big, unprioritised list.

Bringing order to these teams is important for all the member’s sanity while bringing more predictability to everyone who depends on them.

The team’s unit of work: one week sprints

Sprints should last a week. It keeps momentum and people focused.

Two week sprints are great if you’re a mature team with good principles going deep on a multi-month projects. But it doesn’t work for small teams who want a simple process.

Everything is broken down into singular weeks. How did we do this week? What are we doing next week? Simple.

There’s no need for pointing or any of that agile stuff. It’s only a week, and team doing the planning is small. This means there is an instinctive sense of what can be achieved. When the work is broken down well, people can look at their work, think ahead and appreciate the size of it before committing.

The three boards

Managing backlog, up-next and in-progress items on one board is too much to manage.

Perhaps more can be achieved by a fancy tool but it’s usually better to use simple, accessible tools like Trello.

The roadmap board

The roadmap board looks at the next sprints. This is where we break down epics into work delivered week by week.

The roadmap board usually consists of these kinds of lists:

• Epics one list with cards for each major epic the team are working. An epic is anything that takes multiple weeks to deliver, usually this is the stuff that people outside your team will have actually heard of. Link these cards to the high-level requirements. Can also create a label for an epic and assign it to the cards you create.
• Backlogs work assigned to epics but not assign to a week yet. Also useful to create backlogs for Bugs or various house keeping tasks. Clean often otherwise they get too big and useless.
• Future weeks these are are lists for specific weeks, such as “Feb 1-5”. Have at least 3 weeks in the future planned initially. Get better over time and be able to specify further out as you gain predictability.

Having this split out from the main active board is usually the thing that makes a team feel under control. Backlogs are not growing endlessly and the amount of in progress work is not overwhelming.

The active board

This board is the more familiar one you would expect, except it only contains now and next stuff. This turns it from a mess into something can see and then take care of.

Everything in this board should represent a weeks worth of work, that unit of work everyone understands.

The lists here are as you expect:

• Todo / ready to start the tasks you’ve agreed to work on this week and no more. If you’re not working on it this week then take it off the board.
• In Progress the tasks that are in progress, moved by the owners of the cards when they start them so others know they are being worked on
• Blocked tasks that the owner cannot make progress on. This is bad. Deal with these ASAP and never let them back up.
• Done tasks assigned in this week and completed this week

You can add other lists like “QA” or “testing” or “PR review” in this list as-well, if that works with your process. Keep these lists to a minimum. Just focus on easy flow from left to right and highlighting blockages.

The done board

This is the best board - every week move the “Done” list from your active board here.

Every now and then take a peek at this board and see how much you’ve done.

The PM, aka the card whisperer

To really make this work you’ll need someone who has the responsibility to keep the process moving. Resolving blockers, filling up future weeks and assigning owners.

Ideally, this will be someone with Product/Project Manager in their title. However it doesn’t always work out that way, especially in small teams.

Whomever it is, the person should be senior enough to know enough detail about each card to make priority decisions. This person should focus on flow, keeping the team delivering according to the whatever priority is at time. This person can then relay progress back to the wider business.