A good reason to use TODO

On my first job, there was a vestigial TODO that always bothered me. It said

/* TODO: PSJB, Is this right? -AW */

I eventually figured out that “PSJB” were the initials of our CEO (who wrote a lot code for the early versions). I knew who AW was, but he left before I started, so I couldn’t ask him what this meant. I wanted to just delete it, but I could never figure out if the code it referred to was right. I left the company before figuring it out—the comment might still be there.

This was a bad way to use TODO.

To avoid this problem for others, for my last PR at Atlassian, I searched for every TODO that I left in the code, which was possible because we were forced to sign them. I resolved each one in some way and then removed it. Saying “toodle-oo” by removing “TODO: Lou” from our code made me smile.

None of these TODOs were there for good reason.

Since I’m 100% in charge of my code style guide these days, I don’t allow TODOs to be merged (it won’t pass linting). But, I do use TODO in the code while I am building a PR if it’s convenient—I’ll be forced to remove it before merge.

The only other TODO I’m ok with is ones that are going to be resolved very soon (within the grace period)—hopefully in a stacked PR.

If you have (tech) debt, inflation is good

I rent my apartment. I moved here in 2018, and over the last 5 years (because of many factors, but mostly inflation), my rent has gone up about 30%. Inflation over that time is about 22%, so it’s even gone up in constant dollars.

If you had a fixed-rate mortgage, your payments would have gone up 0%. When you have a mortgage, inflation makes housing costs relatively smaller in your total budget because everything else goes up. If your interest rate is lower than inflation, then you get to pay the debt back in lower-value dollars.

The same is true for tech debt where inflation is the increasing size of the codebase and the team. Writing more code shrinks the relative cost of the debt you have. Having more team members makes paying tech debt a smaller proportion of your work.

If you had a metric of tech-debt, new good code would tend to lower it. This is true as long as interest on the tech debt is not too high. For tech debt, interest payments are only due if you want to change the code.

If your roadmap requires you to mostly change tech-debt-laden code, then inflation is low (no new code) and so the interest payments are high. This is a good time to prioritize paying tech debt down.

Conversely, code that has debt, but basically works and is not going to be changed, is like having a 0% loan. You have the loan. It may one day come due, but at least you don’t have to service it if you don’t want to. If your team and codebase doubles in size, that debt will feel smaller.

How to Lower Tech Debt with One Easy Trick

Yesterday, I wrote about the Tech Debt Detectors that I use in Visual Studio Code.

Here’s what it looks like for one of my CRAP-y functions. The red bars in the left-gutter show that I don’t test this function at all, and the red square at the end of line 4 shows that it has a lot of branches.

I wrote this function to make it easier to call GQL Mutate functions with boiler-plate error handling. This function reduces the complexity of each calling function. I am ok with this being complex, so to reduce CRAP, I should be testing each branch. I was surprised that I didn’t already do this, because I test GQL calls with a mock server. I did a full text search for for the function name, and I see that … I NEVER USE IT?!

Ah yes, now I remember. I didn’t like that this code wasn’t type-safe, so I generated type-safe variants from my queries (see Why I am Using Code Generation Again, Part I and Extending GraphQL Code Generation (Part II).

I never removed this function after migrating all code to the new version, so I did it now. Deleting code is a great way to lower tech debt. No code—no debt.

Tech Debt Detectors

When I wrote Use Your First Commit to Fix CRAP I said that “there are extensions for many IDEs to get you the [CRAP] metric directly”, but I hadn’t installed any. I thought that the two components of CRAP were easy enough to notice without them, but that’s only half-way true. Today, I use two extensions for Visual Studio Code to help make CRAP-y more evident to me.

Note: The CRAP metric indicates that a function is risky to change because it’s complex and undertested. To fix the function, you either need to break it into smaller functions or add tests—both actions are generally good, so it’s a metric that’s hard to game.

The first component of a CRAP-y function is its complexity, which you can estimate by counting its branches. So, count each if/else-if/else, case in a switch, loop/break/continue, and each or/and in your boolean expressions. You are trying to get an idea of how many paths there are. Since, you want to keep function complexity very low, you really don’t need to count every branch—you can stop at some low (single-digit) number. It isn’t hard to estimate a YES/NO answer to the question of complexity for any particular function, but the problem is remembering to ask.

To get complexity in Visual Studio Code, I am using CodeMetrics by Kiss Tamás. For each function, the extension shows a green, yellow, or red indicator and a short message above the function.

The second component of CRAP is test coverage. To show that in my editor, I use Coverage Gutters. This extension shows red and green markers to the left of the code to indicate if a line was run during tests. It needs you to generate standard code coverage files, which jest can do for me. It should support any language that has standard coverage support (i.e. in lcov format).

I’ll show some examples of what this looks like and how I fixed problem areas in upcoming posts.

Projects that fail never pay off tech debt

I just shut down a project I started in October 2021. It was code for a startup, but it turned out the idea didn’t have traction, and my partner and I decided that it wasn’t worth pursuing. The tech debt in this project will never be paid. If I had been paying it all along, it would have been a waste of time.

This was not a full-time project for me, and I am the only developer on it, so there’s not a ton of code. But, even a three-month project could have a little debt, so even though it’s not that old, it had some debt.

Like most projects, it had dependencies. I just checked my yarn.lock files and I see that the last time I did an update was about a year ago. I consider all third-party dependencies to be tech debt, especially as they get out of date, so that’s one that’s always building on most projects. The only way to avoid dependency debt is to not have dependencies. Which, in a way, is true now.

The biggest codebase issue that I was wrangling with was authorization. The permission model was getting a little out of control, and the code wasn’t helping make sense of it. I had been planning something more attribute based in the code, but well, now I don’t have to worry about it.

If there’s a lesson to learn here, it’s this: Don’t rush to pay off debt in projects that have a good chance of dying. The goal should be to get customers. To the extent that it’s not externally perceivable to customers, code health is usually not much of a factor in early traction.

Tech Debt in a 3 Month Old Project

I’ve been working on a new web app since October. The backend is a GraphQL API on top of a database schema. Each entry point unpacks the request and then calls a function that queries or mutates the database. There are some complex mutations—ones where there might be updates, inserts, and deletions that all need to succeed or fail together.

I know that I’m supposed to do this with transactions, but I was also using an ORM that I’m not very familiar with, and wanted to make progress quickly. I decided to pay lip-service to transactions, wrap some functions in them to indicate to myself that I needed to think about them, but mostly just ignore them. I would never not do transactions in a production app, but for this, it made sense.

After MVP, a month or so ago, I’ve just been adding minor things while my partner onboards some trial users. Eventually, I tried to implement a feature where the API call could result in many inserts and deletions, and I could see in tests that I could cause this to fail in ways that corrupted the data.

So, I had to stop, learn how to do transactions in this ORM, and then implement them in my data code. It took a few hours, and now the debt is paid off.

I do this kind of short-term borrowing/paying of debt all of the time. I am borrowing to keep myself in flow. I try to keep the debt top-of-mind by making it very evident in the code. It’s like using a credit card where you pay it off inside the grace period.

Accountability Affinity

Last year, I struggled to find a local author’s group, and realized that it mattered if the others were basically in my genre. The first one I tried was mostly attended by memoir writers. The second, Shut Up & Write, was mostly fiction writers. It was fun to attend, but I didn’t find much common ground, and so I stopped going to them.

Yesterday, I joined the Useful Books community, which is a community of authors that are writing non-fiction books based on ideas in Write Useful Books by Rob Fitzpatrick. He’s in tech, but the community is more broad than that—the genre is described as useful non-fiction: “to create a book so useful that readers can’t help but recommend it.” I went to a virtual writing session yesterday and did end up getting a lot done—and it carried through to the rest of the day.

It’s early on, so I don’t know if this will stick yet, but I do think having something in common with the group helps. Not just that we’re all trying to write, but also the type of thing we’re writing.

4DX: Applying the Fourth Discipline

See 4DX: Applying the Third Discipline to get a summary of the WIGs and Lead Measures.

The final discipline is to have weekly accountability meetings that are only about 4DX, the WIG, the lead measures and how to do better in the coming week.

This is hard because I mostly work alone. I do a weekly retrospective, so I mostly need to just make sure I always review my scoreboard from the 3rd discipline.

For my fitness goal, I go to Crossfit which puts me in a room with several coaches and peers. I track my lifts in the gym’s app, which I share. If I stumble with this goal, I may add more direct accountability.

For my work goal, I have a partner and we already have weekly status meetings. They are not 4DX specific, so again, if this goal is not reached by March 31, then I may ask for 4DX meetings.

For my personal growth goal, I have decided to share my progress in a weekly podcast. I just joined the Useful Books community in order to meet like-minded people and perhaps join an accountability group.

For all three of my WIGs, I am not yet really doing the fourth discipline correctly, but I will try to move towards that as I progress.

Grouper with Orange Sauce

Today is my wife’s birthday, and I don’t have time to write, so I’ll just share a recipe for part of the dinner I made for her

Ingredients

  • 1 fillet of Grouper, approx 1/3 pound
  • Flour to dredge
  • Butter (a few pats to cook and then about 1-2 tbs for the pan sauce)
  • Olive oil (1 tbs)
  • Juice from 2 mandarin oranges (I put peeled oranges in immersion blender and strained)
  • Zest from 2 mandarin oranges
  • Shallot, very finely minced, about 2-3 tbs
  • Thyme (1 tsp)
  1. Heat a pan over medium heat
  2. Put flour on a dinner plate, season with salt and pepper to taste
  3. Dredge Grouper in flour
  4. Melt pats of butter in olive oil in pan
  5. When the pan is hot, place grouper in it, don’t move the fish—let it sear.
  6. Depending on thickness, turn when first side is ready (4 or more minutes). Fish should be easy to flip—look for some browning.
  7. After second side is cooked, put aside or move to side of pan off direct heat (make sure it’s cooked through)
  8. Put shallots and zest in pan for about a minute
  9. Deglaze pan with juice
  10. Add butter, continue deglazing
  11. Add thyme
  12. Put grouper back in pan and coat with sauce
  13. Put sauce on plate and fish on top of it

If you want more instructions, see this page for how to pan sear grouper. They have a different sauce, which you might also like.

I served with roasted red potatoes and steamed haricot verts with almond slivers.

Enjoy!

4DX: Applying the Third Discipline

Previously:

Now we have Wildly Important Goals (WIGs) and Lead Measures to act on.

  1. Work: Get to no launch blockers in the product by March 31 by spending 4 hours per week on them
  2. Fitness: Go from 23% body fat to under 20% by December 31 by doing 4 strength workouts per week and having 5 high-protein breakfasts per week.
  3. Personal Growth: Publish two 50-page books by December 31 by working on them 5 days per week for at least one hour per day.

The third discipline is to build a compelling scoreboard. The idea is that it’s like a scoreboard in any sport—you can look at it and instantly see if you are winning.

The trick is to build a player’s scoreboard and not a coach’s one. In basketball, a coach would have free-throw percentages, blocks, assists, and many useful pieces of data. The player has points and fouls and little else. Player’s need signals to help them make quick decisions, not tons of data to analyze. While we’re working, we’re players, and we need to know if we’re winning at a glance. The other data is collected and we (or our managers/coaches) might analyze them, but we don’t need to see it all of the time. We always need to know the score and whether we’re winning.

To keep this simple, I decided to dedicate a page on my journal to the first 13 weeks. I have 13 rows (one for each week) and then columns for each lead measure. I just need to put an X in the column when I do it. I can see my current week and compare it to the past. I’ll make a new grid every 13 weeks.

A page from a journal showing the WIG / Lead Measure scoreboard for 13 weeks.

I also track in software. Since I use an Apple Watch, I just start a Strength Workout on it right before I start to lift. The data shows up in many fitness apps I use daily. For the other two WIGs, I am using personal productivity software I am developing. I like the combo of paper and software. The software keeps it in my face when I am at my computer and my journal is always around when I’m not.