← Back

whynot what

The if-statement nobody could explain

Stopped re-deriving decisions I'd already made

feedback · process

Early at Zipy I was building features end to end: the database tables, what went into Redis and why, how the pieces fitted together. My CTO told me I kept redoing the same thinking. Every time I came back to a feature, I worked the decisions out again, because I had never written down why I made them the first time.

She was right, and I found out how right a few weeks later.

Inside the browser SDK there was a condition that handled one particular kind of error object. Somebody had clearly put it there on purpose. Nothing said why. Then a customer hit a bug that pointed straight at that line.

That left me with a coin flip. Change it, and possibly break something a customer was relying on. Leave it, and fail to fix the bug in front of me. A live decision, resting entirely on reasoning that nobody had written down.

Two habits came out of it. Any condition handling a special case gets a comment naming the real situation it is there for. And every feature gets its own folder on the shared drive with a design doc in it, holding the reasoning behind the decisions.

It did not remove rework. Some rework is just systems changing underneath you. But I stopped re-deciding things I had already decided once.