Informal Work Lists

There are many ways I learn about new tasks. Email, Github, issue trackers, chat, and my memory all chip in. I have to copy these tasks over to a single place or I'll spend a lot of time worrying that I'm forgetting something.

I think engineering teams can face a similar problem, tracking tasks and work in progress in many different places. Here are some examples of todo lists teams keep, that maybe aren't immediately recognizable as such.

• The collection of TODO comments in code pretty literally compromise a todo list.
• Skipped tests represent work in progress. The work will be finished either when the test is fixed and un-skipped, or removed.
• Each experimental feature flag represents some work in progress. Once the work is finished the flag can be removed again. (I realize there's other uses for feature flags that don't count as work in progress).
• Debug instrumentation running in production to help understand a specific issue of our code represent work in progress. Once the problem is understood the instrumentation can be removed again.

The risk I see here is these are basically backlogs with all the associated costs, but these costs aren't necessarily obvious. In fact its super easy to add an item of work in any of these categories. Removing an item of work can be much harder, especially if we are not or no longer the person with context on why the task was added.

We can mitigate some of the risk using by adding some enabling constraints:

• CI can reject PRs that contain TODO comments. That way TODO comments can be used as a reminder system while working on a PR, but any that remain when the PR is done will have to be moved into the team's backlog proper. Assuming folks take more care writing a backlog issue than a TODO comment (this is true for me), this can force us to reflect on whether the thought represented by the TODO is really worth turning into a ticket. If you don't want to loose the ability to add TODO comments in PRs but do like these needing to be added to the teams tracker, an alternative system is to enforce that TODO comments need to include a link or issue number.
• Similar to TODO comments, consider failing CI on skipped tests, or fail CI when skipped tests aren't accompanied by a link to a ticket.
• We can have a convention of adding comments to each feature flag, specifically explaining under what circumstances it will be flipped and when it can be removed. Answering these questions can help us figure out if adding a feature flag is the right move, and help future us or others remove the feature flag once it has served its purpose.
• Similar to documenting feature flags, a convention of commenting on debug instrumentation that answers the same two questions: when is this going to be used and when can we remove it?

These small process changes can help us make more conscious decisions about whether to create future work for ourselves. And when we decide to go forward, set our future selves or others up better to complete the work, or decide to remove the task.