In most cases, the TODO should be filed in your team’s issue tracker immediately and cross-linked with the pull request. Some people have processes that track issues using TODOs, but I don’t believe source code works well for issue tracking. Source code represents the current state of your product. Reviewing historical context, though possible with version control, is not the primary interface. Issue tracking systems are built for prioritization, tracking context, linking related issues, and assigning responsibility.

TODOs are usually used to defer technical debt. Moving them to your issue tracker’s backlog allows prioritization against feature work by putting them in the same playing field and can be used as a metric to understand the depth of technical debt.

TODOs often describe an expected future change. It’s tough to predict the future, so the TODO might not make sense when the next person reads them. I still encourage using comments to describe the problem and the reasons for not addressing it, but not to prescribe action. In the future, you’ll have much better context when deciding how to fix the issue, or you might be able to just delete it.

Even though I don’t like seeing TODOs in a codebase, I often use them in my feature branches and scan through the diff once I’ve opened my draft PR to decide if it’s ready for review. They’re lighter weight than an issue tracker and can act as a checklist for a single task. Generally, though, they’re an indicator of poor quality and have more responsible alternatives.

1. Messages are not searchable once you leave
2. Messages are not sharable
3. People can’t easily jump in and out
4. You can’t notify someone when you mention them
5. Workspace apps and bots aren’t present
6. They cultivate an “Us vs. them” culture
7. They foster unconscious biases by making it easy to exclude people
8. You can’t change your mind and make a private channel public

While there are uses for private channels, they hinder communication and transparency. Please make public channels your default.

The IDE, the language, and the execution of the code itself all support and guide me as I write code. Especially when executing on a pre-designed plan or refactoring, I can rely on the compiler to let me know when I’ve made a mistake and I can look at the UI to see if I’ve done it right. Some tasks can even feel refreshing because they don’t require hard thinking while seeing a lot of output.

Pure technical design is far harder. Without supporting tools, a higher percent of the cost comes from my brain. I can’t lean on a program to tell me I’m doing something wrong or tell me what to think about next.

To help, I try to prototype in parallel. Whatever code I produce I leave out of review to avoid sunk-cost bias and avoid “can’t see the forest for the trees” effect.

The issue is that I can’t see the future. It’s close to impossible to understand the details of the future use cases I’m building for, and more often then not I’m going to get it not quite right. Once that happens, the work I put in building my abstraction layer is far less valuable and it often gets in the way, making my job harder.

Working in a fast-growing company also means that a lot of the time the future use case I’m building for just never happens. We decide to go another direction, or pause on that project, or it just doesn’t get prioritized. Two years later, the system has evolved to the point where what I built just doesn’t make sense.

Truth is relative

Over time, my understanding of systems will always change, due to the complex and changing environment I work in. Be it because of the tools we use, the people we work with, or the size of the organization, decisions are never binary or always correct. Choosing to use a statically typed language might be more important if the scale of the project is larger, or if a coworker hasn’t developed the muscles to think dynamically. Building a massively scalable microservice architecture might mean you can’t deliver an MVP in time to get the funding needed to start growing your start-up. Implementing a policy to never force-upgrade an app version doesn’t work once Brexit happens.

Build defensively

What you can do is build defensively. In essence, this means building with the understanding that it will be wrong in the future. Encapsulation helps a lot with this, as it enables you to extract or split apart functionality with less pain. Another simple defensive technique is to write less code and save the up-front and maintenance cost.

My rule of thumb

Unless you have three real use cases to build against, don’t spend extra time making the solution generic.

The word “real” is intentional because of my comments on predicting the future.

The words “extra time” are also intentional. Generic abstractions can be useful on their own, to hide complex logic or simplify a difficult to use API, or to build a layer of defence; but if the main value in abstraction is for future elegance it’s not worth it.

Building an abstraction layer is the most problematic with only a single use case, primarily because it usually adds more maintenance overhead which slows iteration and maintenance. The “abstract” interface will often look very similar to the internal one and refactoring is often not any easier than IDE assisted renaming.

Building with two use cases is also problematic. It will be very tempting to add flag-based logic into the implementation, or worse, the external interface. When a third use case is added, the most obvious method is to continue using flag-logic, which ends up coupling the interface to the implementation. The value of the abstraction is lower but maintenance cost isn’t.

Three use cases, however, covers enough complexity that you’re forced to understand what the real value of the abstraction is and create it in a way that makes it easier to work with.

One of the fundamentals of programming is defining interfaces, or contracts between parts of systems. Interfaces create layers of abstraction and allow scaling code beyond the complexity a single person can hold in their head. They appear at the level of function signatures, to dependency signatures, up to service-to-service network calls.

There are almost always grey areas within an individual interface; areas where behavior isn’t explicitly defined. This causes a couple problems. Interpretations of behavior can differ between people or over time, leading to subtle bugs due to drifting behavior in different modules. It also requires overhead and more error handling in each consumer, as you’ll see below.

In a strongly typed language there are some not-immediately-obvious techniques to reduce this ambiguity and create a more intuitive design.

I’ll provide code examples throughout this post, available in several different languages.

The basics: Comments

As the author, the easiest way to avoid ambiguity is through documenting your code.

interface Foo {
  type: string; // describes how foo should be represented
}

interface Bar {
  discount?: number;
  discountApplied?: boolean; // indicates if `discount` is possible, or actually applied, not present if no discount
}

data class Foo(
  val type: String // describes how foo should be represented
)

data class Bar(
  val discount: String?,
  val discountApplied: Boolean? // indicates if `discount` is possible, or actually applied, not present if no discount
)

type Foo struct {
	Type string // describes how foo should be represented
}

type Bar struct {
	Discount        *string
	DiscountApplied *bool // indicates if `discount` is possible, or actually applied, not present if no discount
}

components:
  schemas:
    Foo:
      type: object
      properties:
        type:
          type: string
          description: describes how foo should be represented
    Bar:
      type: object
      properties:
        discount:
          type: string
          nullable: true
        discountApplied:
          type: boolean
          nullable: true
          description: indicates if `discount` is possible, or actually applied, not present if no discount

This helps, but couples you to additional tooling within your editor to expose without reading the source. Comments don’t protect against human issues, such as misinterpretation or plain laziness, and conformance can’t automatically be verified by build tooling.

Taking advantage of typing

Enums

A simple pattern is to use enumeration values. Explicit enumerations can reduce the need for inline error handling and allows for self-documentation through good naming. This sounds simple, but I see people forget about enums often. The key question to ask is:

Do I care about how the consumer uses this value?

If the answer is yes, a string type doesn’t capture the correct nuance.

interface Foo {
  type: string;
}

function convertFooTypeToX(x: Foo): string {
  switch (x.type) {
    case "a":
      return "1";
    case "b":
      return "2";
    case "c":
      return "3";
    default:
      throw new Error(`unknown type: ${x.type}`);
  }
}

enum FooType {
  a = "a",
  b = "b",
  c = "c"
}

interface Foo {
  type: FooType;
}

function convertFooTypeToX(x: Foo): string {
  switch (x.type) {
    case FooType.a:
      return "1";
    case FooType.b:
      return "2";
    case FooType.c:
      return "3";
    // no default is required to satisfy type checking
  }
}

data class Foo(
    var type: String
)

fun convertFooTypeToX(x: Foo): String = when (x.type) {
    "a" -> "1"
    "b" -> "2"
    "c" -> "3"
    else -> throw Exception("unknown type: ${x.type}")
}

enum class FooType {
    a,
    b,
    c,
}

data class Foo(
    val type: FooType
)

fun convertFooTypeToX(x: Foo): String = when (x.type) {
    FooType.a -> "1"
    FooType.b -> "2"
    FooType.c -> "3"
    // no else is required to satisfy type checking
}

type Foo struct {
	Type string
}

func ConvertFooTypeToX(x Foo) string {
	switch x.Type {
	case "a":
		return "1"
	case "b":
		return "2"
	case "c":
		return "3"
	}
	panic(fmt.Sprintf("unknown type: %s", x.Type))
}

type FooType string

const (
	FooTypeA FooType = "a"
	FooTypeB         = "b"
	FooTypeC         = "c"
)

type Foo struct {
	Type FooType
}

func ConvertFooTypeToX(x Foo) string {
	switch x.Type {
	case FooTypeA:
		return "1"
	case FooTypeB:
		return "2"
	case FooTypeC:
		return "3"
  }
  // unfortunately, without real enums in go, we still need this
	panic(fmt.Sprintf("unknown type: %s", x.Type))
}

components:
  schemas:
    Foo:
      schema:
        type: string

components:
  schemas:
    Foo:
      schema:
        type: string
        enum: [a, b, c]

String formats

Enums work well, but only work for explicit sets of values—they can’t be applied if I don’t know the full set of values. If I do know, adding anything new breaks backwards compatibility.

To get around this, I can use a type alias to provide more semantic information.

type HtmlType = string;

typealias HtmlType = String

type HtmlType string

components:
  schemas:
    Foo:
      schema:
        type: string
        format: html

There’s a loophole: The consumer could create their own string and pass it in place of HtmlType. Depending on the serialization library and language, it can be possible to discourage this with custom deserialization of a non-constructable type.

type HtmlType = string & { __t: "html_type" }

function read(response: Response): HtmlType {
  return response.body as HtmlType;
}

class HtmlTypeDeserializer extends JsonDeserializer<HtmlType> {
  @Override
  fun deserialize(JsonParser jp, DeserializationContext ctx) throws IOException, JsonProcessingException {
    // read contents of jp...
    return HtmlType(content)
  }
}

@JsonDeserialize(using = HtmlTypeDeserializer::class)
class HtmlType private constructor(private val content: String)

// no example in this language

# no example in this language

In the real world, it’s risky to migrate to a format from an existing enumeration. There’s often logic in the client that depends on knowledge of a specific value, and all that logic needs to be transformed into an api driven model. It’s tempting to keep it in the client, but that makes removal of the value not-backwards compatible and undocumented.

Nested nullables

A common pattern I see when designing api responses is to use a flat structure like the following.

interface Workout {
  swim_id: string | null;
  swim_miles: number | null;
  swim_time: Time | null;
  bike_id: string | null;
  bike_miles: number | null;
  bike_time: Time | null;
  run_id: string | null;
  run_miles: number | null;
  run_time: Time | null;
}

import kotlin.time.Duration;

data class Workout(
    var swim_id: String?,
    var swim_miles: String?,
    var swim_time: Duration?,
    var bike_id: String?,
    var bike_miles: Double?,
    var bike_time: Duration?,
    var run_id: String?,
    var run_miles: Double?,
    var run_time: Duration?
)

type Workout struct {
	SwimID    *string
	SwimMiles *float64
	SwimTime  *time.Duration
	BikeID    *string
	BikeMiles *float64
	BikeTime  *time.Duration
	RunID     *string
	RunMiles  *float64
	RunTime   *time.Duration
}

components:
  schemas:
    Workout:
      type: object
      properties:
        swim_id:
          type: string
          nullable: true
        swim_miles:
          type: number
          nullable: true
        swim_time:
          type: number
          nullable: true
        bike_id:
          type: string
          nullable: true
        bike_miles:
          type: number
          nullable: true
        bike_time:
          type: number
          nullable: true
        run_id:
          type: string
          nullable: true
        run_miles:
          type: number
          nullable: true
        run_time:
          type: number
          nullable: true

This leads to open questions: What happens a mix of id, miles, and time is present? Should I always expect miles to be present if id is present? How does time relate to miles?

By breaking up the flat structure these can be answered.

Here, it’s clear that an id is always paired with miles and time, and each type of activity might be missing:

interface Segment {
  id: string;
  miles: number;
  time: Time;
}

interface Workout {
  swim: Segment | null;
  bike: Segment | null;
  run: Segment | null;
}

import kotlin.time.Duration;

data class Segment(
    val id: String,
    val miles: Double,
    val time: Duration
)

data class Workout(
    var swim: Segment?,
    var bike: Segment?,
    var run: Segment?
)

type Segment struct {
	ID    string
	Miles float64
	Time  time.Duration
}

type Workout struct {
	Swim *Segment
	Bike *Segment
	Run  *Segment
}

components:
  schemas:
    Segment:
      type: object
      properties:
        id:
          type: string
        miles:
          type: number
        time:
          type: number
    Workout:
      type: object
      properties:
        swim:
          $ref: "#/components/schemas/Segment"
          nullable: true
        bike:
          $ref: "#/components/schemas/Segment"
          nullable: true
        run:
          $ref: "#/components/schemas/Segment"
          nullable: true

With this alternate structure, I can see that the other fields might be missing:

interface Segment {
  id: string;
  miles: number | null;
  time: Time | null;
}

interface Workout {
  swim: Segment | null;
  bike: Segment | null;
  run: Segment | null;
}

import kotlin.time.Duration;

data class Segment(
    val id: String,
    val miles: Double?,
    val time: Duration?
)

data class Workout(
    var swim: Segment?,
    var bike: Segment?,
    var run: Segment?
)

type Segment struct {
	ID    string
	Miles *float64
	Time  *time.Duration
}

type Workout struct {
	Swim *Segment
	Bike *Segment
	Run  *Segment
}

components:
  schemas:
    Segment:
      type: object
      properties:
        id:
          type: string
        miles:
          type: number
          nullable: true
        time:
          type: number
          nullable: true
    Workout:
      type: object
      properties:
        swim:
          $ref: "#/components/schemas/Segment"
          nullable: true
        bike:
          $ref: "#/components/schemas/Segment"
          nullable: true
        run:
          $ref: "#/components/schemas/Segment"
          nullable: true

And here, I understand that the statistics might be missing, but are tied together:

interface Segment {
  id: string;
  stats: {
    miles: number;
    time: Time;
  } | null;
}

interface Workout {
  swim: Segment | null;
  bike: Segment | null;
  run: Segment | null;
}

import kotlin.time.Duration;

data class Stats(
    val miles: Double,
    val time: Duration
)

data class Segment(
    val id: String,
    val stats: Stats?
)

data class Workout(
    var swim: Segment?,
    var bike: Segment?,
    var run: Segment?
)

type Stats struct {
	Miles float64
	Time  time.Duration
}

type Segment struct {
	ID    string
	Stats *Stats
}

type Workout struct {
	Swim *Segment
	Bike *Segment
	Run  *Segment
}

components:
  schemas:
    Stats:
      type: object
      properties:
        miles:
          type: number
        time:
          type: number
    Segment:
      type: object
      properties:
        id:
          type: string
        stats:
          $ref: "#/components/schemas/Stats"
          nullable: true
    Workout:
      type: object
      properties:
        swim:
          $ref: "#/components/schemas/Segment"
          nullable: true
        bike:
          $ref: "#/components/schemas/Segment"
          nullable: true
        run:
          $ref: "#/components/schemas/Segment"
          nullable: true

This avoids type asserations and null pointer errors: workout.swim_id!: workout.swim_id!!: panic: runtime error: invalid memory address or nil pointer dereference.

Type unions

Another type structure that can reduce ambiguity is a union type. Union types allow representing “exclusive or” in the interface and avoid locking in an inheritance structure. Kotlin’s sealed classes are a good way to implement these. This is a first class feature in Typescript.

For example, say I want to represent a figure on my site.

interface Figure {
  source: string;
  attr: string;
  height?: number;
  width?: number;
}

data class Figure(
    val source: String,
    val attr: String,
    val height: Int?,
    val width: Int?
)

type Figure struct {
	Source string
	Attr   string
	Height *int
	Width  *int
}

components:
  schemas:
    Figure:
      type: object
      properties:
        source:
          type: string
        attr:
          type: string
        height:
          type: number
          nullable: true
        width:
          type: number
          nullable: true

This works, but allows for accidentally distorting the image by specifying a height and width that doesn’t match the aspect ratio. A type union can prevent this.

type Size = {} | { height: number } | { width: number };

interface UnsizedFigure {
  source: string;
  attr: string;
}

type Figure = UnsizedFigure & Size;

sealed class Figure(
    open val source: String,
    open val attr: String
)

class UnsizedFigure(
    override val source: String,
    override val attr: String
): Figure(source, attr)

class HeightSizedFigure(
    override val source: String,
    override val attr: String,
    val height: Int
): Figure(source, attr)

class WidthSizedFigure(
    override val source: String,
    override val attr: String,
    val width: Int
): Figure(source, attr)

type UnsizedFigure struct {
	Source string
	Attr   string
}

type HeightSizedFigure struct {
	UnsizedFigure
	Height int
}

type WidthSizedFigure struct {
	UnsizedFigure
	Width int
}

type Figure interface{}

components:
  schemas:
    UnsizedFigure:
      type: object
      properties:
        source:
          type: string
        attr:
          type: string
    Size:
      oneOf:
        - type: object
          properties:
            height:
              type: number
        - type: object
          properties:
            width:
              type: number
    SizedFigure:
      allOf:
        - $ref: "#/components/schemas/UnsizedFigure"
        - $ref: "#/components/schemas/Size"
    Figure:
      oneOf:
        - $ref: "#/components/schemas/UnsizedFigure"
        - $ref: "#/components/schemas/SizedFigure"

Type unions force explicit checking of which type is used. They’re possible in many languages, but not all.

function isHeightSized(x: Size): x is { height: number } {
  return (x as { height?: number }).height != null;
}

function isWidthSized(x: Size): x is { width: number } {
  return (x as { width?: number }).width != null;
}

fun eval(figure: Figure): Int = when (figure) {
    is UnsizedFigure -> 0
    is HeightSizedFigure -> 1
    is WidthSizedFigure -> 2
}

func eval(figure Figure) int {
	switch t := figure.(type) {
	case UnsizedFigure:
		return 0
	case HeightSizedFigure:
		return 1
	case WidthSizedFigure:
		return 2
	default:
		panic(fmt.Sprintf("Unknown type: %v", t))
	}
}

# See other languages for reference implementations.

In the real world

These techniques can give great build-time safety when applied within a single codebase, but it’s harder to apply that safety across different codebases (e.g. calling an api, or using a typescript dependency in a javascript codebase). Responsibility for conforming to the contract has been absolved from the consumer and has been shifted explicitly to the producer. Since there’s less incentive for explicit protection through validation in client code, errors caused by backwards incompatibility are harder to track down. Documenting changes through the use of techniques like semver make this easy to avoid.

Introducing into an existing system

In a well-established environment it’s sometimes not possible to apply these patterns in the producer; especially when dealing with legacy systems or other teams. In these cases these patterns can be introduced in the middle of the stack, either within a fronting service or a module within the consuming client. This gives an explicit place to add validation and audit that the contract is being followed.

To summarize: Introducing more complexity into your interface; be it a function call, library, or api; makes it harder for consumers to make the wrong assumptions without asking them to think about logic outside of their business domain.

To start, what does understanding actually mean? To paraphrase others:

To fully understand something you should be able to explain it to someone else.

Getting there takes time. In my experience there are a number of stages along the way, and I’ve found that recognizing where I’m at helps me avoid mistakes and accelerates the learning process understanding faster.

In this post, I’m going to describe these stages as I understand them and how I use them.

I don’t understand

At this point I’m aware that I don’t understand. I’ve moved past the Peak of “Mount Stupid” and I’m in the “Valley of Despair” in the Dunning–Kruger curve. This is a safe place to be, since the though that I might be doing things wrong is top of mind. When I’m writing code, I pay much more attention to what I’m doing and try to communicate my questions to other reviewers, so they also take a closer look. I also take more time to build safeguards into my code during this phase because the likelyhood of future change is higher.

I can copy and extend

At this stage, I can build upon existing patterns, and I’m starting to see the shape of those patterns. This is where I generally learn the fastest, but only if I’m paying attention. It’s key here to avoid cargo culting while recognizing the cost—it takes time and mental energy.

When I’m working with someone else who’s at this level I trust them to work independently, given they have patterns to copy and their code is well-reviewed.

I know enough to be dangerous

This is the riskiest level, and the best way to get through it quickly is to take personal responsibility. At this stage I know a few patterns, but not how to apply them. A specific example is when I first learned about go modules and packages. I knew how to set up my project to use packages from external dependencies, but not how to apply the package organization structure to my own project. In order to get stuff done my project grew to have have excessively long files and code duplication. Since I knew I wasn’t following the right pattern, I was able to separate responsibility within my code to allow it to be extracted in the future.

A specific technique I use here is to read each line in my change and spot check if I have a basic understanding of why I had to change it. If I don’t, I revert it and see what happens.

Double check all your assumptions and pay attention. Automated tooling and testing (e.g. automated tests and linting, good gitignore files) will help a lot here and reduce the need for hand-holding.

I’ve got a bad feeling about this

At this point I’m able to, both with my own work and when reviewing others’, instinctively recognize bad patterns and can sometimes suggestion better replacements. However, I struggle to adequately explain why, or to fully internalize my logic.

With a healthy team, this is a good place to be in. If your team has trust issues, this is a bad place to be. Without being able to explain change requests, the original author won’t see the value. You’ll either need to accept what you feel isn’t quality code or risk breeding resentment.

I often feel stuck in this stage for a long time—sometimes years. I think this is normal. Systems are complex, but recognizing I’m starting to see patterns allows me to be more intentional and introspective, which lets me grow faster.

I can explain what I know

Finally, I’m able to explain clearly. I should be able to simplify the concepts in a way that reduces complexity—such as drawing a systems diagram, creating an analogy, or writing a blog post.

In order to communicate concepts, especially to someone who’s still learning, some nuance will be lost. At any given point I’m missing some depth of detail simply because there are limits to the amount of complexity I can hold in my head at a single point in time.

It’s also important to recognize that complete understanding is unobtainable. There are always differences in opinion and changes over time, and it’s worth reconsidering your assumptions if something doesn’t feel right.