Author Archives: Lou Franco

Write Test Plans for Every PR (and do them)

On the ticket/issue/item attached to your PR, write out the steps to see the change in the application your PR introduces. Even better, record yourself doing them. Not just the happy path, but also show the types of errors that can happen and how the application shows them.

I wish I did this more when I worked on a team, but when I did, everything went smoother through code review and QA. Not because it helped the reviewer or QA engineer—I’m sure it did.

Mostly it helped because I made sure I did all of the steps in the test plan before I posted the PR. Also, writing down a test plan put me more in a tester’s mindset where I was trying to think of things to check and finding problems before I submitted my work.

With all of those things out of the way, the reviewer and QA engineer could concentrate on bigger picture things to check.

How to Find Bugs in a Code Review

I have written that the primary reason to review code is knowledge sharing, not finding bugs, and that the way to use code reviews to prevent bugs is to reject PRs that aren’t obviously correct. But what should you do if you really want to try to find bugs during review?

Run the code—preferably in a debugger from a test.

The best tip I got from Steve Maguire’s Writing Solid Code [affiliate link] was to step through my code in a debugger as I was writing it. The original version of this book (1993) came out before xUnit based unit-testing took off, so I don’t remember him mentioning them. But, I think a unit-test is a better way to do this.

If you don’t have a test that puts you at the line of code you want to inspect, then driving the code manually while stepping through the code in a debugger is a good-enough option. Of course, not having appropriate tests is probably a good enough reason to send the PR back, but if that’s not your team’s culture, and you want to find the problems manually during review, at least use a debugger.

It’s more likely you’ll see problems if you are actively engaging with running code. You will be anticipating what is going to happen as you step through, and if the code behaves differently, you’ll notice. You’ll either find a problem or learn something.

How to use Code Reviews to Prevent Bugs from Getting Into Production

When code has a bug in it, that is way more of an author problem than a reviewer problem. I don’t think it’s right to expect reviewers to find bugs (or to rely on it). It’s way harder to do that unless you actually run the code.

So, I would suggest that to fix the problem of buggy code making it into production, you do more things at the author level, since the author should be running the code a lot through tests and in the debugger. If you have a code reviews checklist, give it to the author, who should be reviewing their own code before PR’ing it.

Then, the reviewer should be verifying that there is evidence that the author actually did thorough work. The review checklist should be verifying the author provided evidence that the author did the pre-PR checklist. Check the tests, check their coverage, check UI screenshots, check that code is doing “something” with edgecases and that those are tested. Instead of looking for bugs, the reviewer should be learning the code and looking for higher level issues.

The author should be providing code that is correct and easy to see that it’s correct. If the reviewer doesn’t think it’s obviously correct, they should reject the PR. The presence of such a review will make the author do more thorough work.

Books That Propelled Me in 2024

These three books did the most to help me make progress in 2024

1. Nonfiction Alchemy [affiliate link] by Jordan Ring

I already finished a draft of my book before I read Nonfiction Alchemy, so I learned some of his lessons the hard way. The biggest change I made after reading it was to my title. I had been using a more literal “promise” based title, but wished it was pithier. His description of how he came up with his title and why helped me come up with Swimming in Tech Debt, which I think works a lot better. The subtitle will do the work of conveying my promise.

The new title is more visual and communicates my main metaphor of using your encounters with tech debt as a trigger to make progress—“swimming” rather than “drowning” in tech debt.

I wrote more about this in Titling a book and Book Title as Visual Metaphor.

2. A Philosophy of Software Design [affiliate link] by John Ousterhout

So many gems—it should be required reading in any CS program. Ousterhout’s target is complexity in software, which is very related to technical debt. My book is more about any code that resists change, which includes well-written, simple, easy to understand code that just can’t be changed in the way you need it to be. This book is about understanding the sources of complexity and fixing them.

3. Slow Productivity [affiliate link] by Cal Newport

This is Newport’s latest book in a continuing series about his approach to work and life. If you haven’t read Deep Work [affiliate link], I would start there and move onto Digital Minimalism [affiliate link]. This book shows how to make big things at a slow pace. I worked on my book in my marginal time: a hour or two a day. But writing hundreds of words a day, a thousand every week, builds up. There were edits, restarts, rewrites, etc. But the pace was sustainable, and I owe a lot of that strategy to this book. (Also see The Four Disciplines of Execution [affiliate link] — which is referenced in Deep Work)

Make Spaces for Things to Track In Your Journal

In Make a Space For Each Day in Your Journal, I wrote that I was more likely to journal every day when there were pages pre-printed with the date on top of them. If I missed a day, I would see the blank space and want to fill it by recreating the day from whatever other sources I had.

This also works on the daily page itself. If there’s something you want to do every day, then pre-printing that on the journal page will keep reminding you to do it. This is one of the reasons I think you should make your own custom journals, because it will be hard to find one that is pre-printed in the way you want.

In 2025, my pages are blank, but I split them in half. The top is meant to be used like a bullet journal. The bottom is a food log. I have found that the biggest impediment to me reaching my fitness goals is not eating as well as I could. In 2022 and 2023 I scribbled my food log in the margin. There wasn’t a lot of room, so I only put the major meals, but it’s the snacking and details that are causing problems for me.

So, by keeping a thorough food log I hope to make it more likely that I will be more intentional in what I eat. Back in 2012, I wrote that you should Take a Picture of What You Eat because just that simple act will influence you—I know from personal experience that having to write down that I ate junk food stopped me from eating it.

Of course, you can do this even if you have something that you want to track weekly or on specific days. In The Four Disciplines of Execution [affiliate link], the third discipline is to make a scoreboard that tells you if you are winning. One way to do that is to pre-print it on your weekly retro page.

In general though, I think it’s more important to have a labeled space than a specific template. Over a year, you might change your mind on what to track. I’d rather have a blank “Scoreboard” area that I am compelled to draw than a rigid one that might go out of date.

Aspirational Plans for 2025

On this blog, when I talk about my annual plans, I am talking about aspirations. The vast majority of my time is spent on living my normal life: work, home, cooking, travel, time with wife, family, and friends, etc. When I look back at 2024, I see what I can do with my marginal time—an hour for fitness and a couple of hours a day to either write or work on my own software added up to a lot.

So, this year I hope to apply that lesson to marketing my finished work better. My strategy is to create content that supports it. I will toot, blog, post on LinkedIn, and email my list — but try to make the content useful in of itself (not promotional). I also want to podcast and YouTube too, but that’s a stretch goal. The written posts don’t take very long—but podcasting and videos are much harder for me.

For fitness, I am going to swim at least twice a week. My apartment has a pool, but I rarely take advantage of it. I need low-impact cardio alternatives anyway, but this will also remind me of my book (Swimming in Tech Debt) and my general 2025 theme to “Just Keep Swimming”. Another advantage to swimming is that it’s very hard to listen to something while doing it, so I have 30 minutes with just my own thoughts—it’s very meditative. It’s an analog hobby that affords solitude (like in Digital Minimalism by Cal Newport [affiliate link]).

My work since the late nineties has been mostly in developer tools or tools for productivity, and even the startup I’ve been working on is in this general area (personal productivity). I want to expand on this. I have ideas for tools that support the themes I write about, and I want to explore those in 2025. To play on my book title and theme, the ideas are fins (to help you go faster) and goggles (to help you see debt better)—I wrote about Tech Debt Detectors on this site and in my book, and these ideas are variations on that.

I’m going to apply The Four Disciplines of Execution [affiliate link] like I did last year, which I’ll write about later this week.

2024 Retrospective

At the beginning of the year, I set out to do three things along the three areas of my life: personal growth, career, and fitness. I had mixed results.

For personal growth, I set a goal to write a 50-page book on a subject in software development. I have been blogging for over 20 years, so I looked over my posts for material and found that I had written a lot about technical debt. I thought there was enough there for a short book, but it needed to be organized and expanded.

I set a goal to write for at least one hour on five days of each week, which was enough to get to fifty pages in a couple of months. It was easy to keep to this schedule because, following the advice of The Four Disciplines of Execution [affiliate link], I joined a writing accountability group. We met three times a week to write together, but adopting their culture of sharing works in progress had the biggest effect on my work. Sharing my text exposed me to conversations that helped me think more deeply about my subject. I didn’t finish the book I set out to write, but I have about 160+ pages with an editor right now, and I plan to release it by March 2025 (sign-up to be notified).

For my career, I wanted to release an MVP of a startup idea I am working on with a friend. We did get an MVP, but realized that it wasn’t the right product, so we pivoted. We are getting close to the next MVP, which is a complete rewrite of the front-end. We hope to onboard a cohort of users in January. I’ll talk about it more when it’s ready to look at.

For fitness, I tried to lose body fat. I tried a lot of things and kept to all of my exercise goals, but nothing I did had an effect. I am satisfied with my overall fitness, but it would have been nice to achieve this. In 2025, I am not going to worry about this any more. I am healthy, and I think I just need to accept my body for what it is: fit, but with a belly.

For each of the three things, I had varying levels of commitment to the actions I set out to do. Writing the book had the highest adherence, probably because of the accountability group. I also had feedback in the middle of the year that people liked my work so far (an excerpt was published in The Pragmatic Engineer). My fitness routine was also easy to follow, also because I was in a group. Working on the startup was harder—there is some accountability, but both of us are doing this on the side, so it gets less time.

In my plan for 2025, I mostly just want to build on what worked in 2024 and finish things up. Here’s what worked and I’ll keep doing

Working in a group—especially literally meeting and working at the same time
Sharing work in progress
Concentrating on hours spent doing activities that will build up to a goal (the lead indicators)

I need to stop doing these things:

Worrying about the things that I might never achieve (like losing body fat)
Setting bars too high on skills in progress. I keep wanting to podcast more, but I’m held back by my inner-audience that doesn’t think it’s good enough.

And I need to start these new things:

Pushing myself out of my comfort zone. In 2025 I need to do marketing for the work that I have done, which means I have to put myself out there more.
Paying more attention to what I eat in addition to my exercise.

Make a Space For Each Day in Your Journal

One thing I have learned in the last two years is that I am much more likely to write in my journal each day if it has a pre-designated space for each day.

In my Recurring Journals I split each open spread of two-pages into quadrants and then put corresponding dates from each 13-week “quarter” in them. So, the first page of 2024 had the Mondays: January 1 and April 1 on the left-hand side and July 1 and September 30 on the right-hand side. The next two-page spread had the Tuesdays: January 2, April 2, July 2, and October 1. I explained why I do this in My Year in Weeks, but the important thing is that every day had a space.

Having a space for each day made it much more likely that I would write something in that space. Even if I missed a day, I went back and recreated it. I did this even when I missed a few days. And because it was a recurring journal, when I got to the end of The First 13 Weeks, I went back to the first page and went through each spread again for The Second 13 Weeks. If I noticed a blank space in the past, I would see if I had any way to recreate what happened that day (from my calendar, git logs, blogs, etc).

This year (2025), I am not going to be using a recurring format, but I am still using pre-dated pages. I will have to be more diligent about checking the previous days, but my weekly retro pages will probably be good enough to make me do that.

Supernote Manta First Impressions

I got my Supernote Manta (A5) two days ago. I haven’t used it much—mostly learning the UI and getting an idea of the features. Mostly, I wanted to get my own 2025 planner on that I made with Page-o-Mat and then get to planning 2025.

Generally, I like it and I still think it is the best choice given my preferences. Here are a bunch of unstructured impressions.

The on-screen keyboard is bad. I hope this can get better in software. Luckily, I think of this as a writing device and won’t want to type much. When I have to, it’s painful.
I wish I could give files names with handwriting (because typing is so bad)
The pen/paper feel is really good—even better than I expected.
The pen doesn’t perfectly make marks all of the time, but no worse than real pens.
The left and right sidebar gestures are ingenious.
Inside of their notes, you can make links to other pages and notes, but you can’t do this inside a PDF. Since standard PDF Annotations supports this, I hope it comes in a software update—I would use that journalling.
I use a passcode to lock the device. I would love it if I could put contact info on that screen so that the journal could be returned if I lost it.

Everything else is as widely reported in reviews. It’s a thoughtful device. I appreciate that I can upgrade the hardware and the software is generally high-quality so far. I am looking forward to having this device for many years.

My Year in Weeks

I released my 2025 Journal PDF (for Supernote) yesterday, and in the middle of describing it, I realized that I have never explained how I plan my year around weeks and 13-week blocks. There are mentions of it in a few posts, but nothing canonical.

I use a week as my main planning timespan, not months or quarters. Additionally, I use Monday as the first day of the week, which is normal for a lot of the world, but not Americans. When I think of how a week flows, the Saturday and Sunday are a unit. I think of them as the start of the week, but almost no software will let you do that, so I got used to them being at the end.

So, all of my projects are estimated in terms of weeks, and I program in sprints that are a multiple of weeks. Then, I split the year into four 13-weeks “quarters”, which is close to a year (364 days). This year, 2024, started on a Monday, and because it was a leap year, April 1 and July 1 were exactly on 13-week boundaries (Oct 1 was only a day off), so my system correlated to normal quarters about as well as it ever could. This doesn’t happen again until 2052. I hope I am there to see it and that I still care.

My journal is set up to follow the flow of a week. Days of the week tend to be similar to each other—so, there is a feel to a Monday, a Tuesday, a Sunday, etc. But March 3rd will not be like April 3rd or October 3rd. A lot of recurring meetings are weekly or bi-weekly, or on the “Third Thursday of the Month” or some other pattern that works well with my system.

When a year doesn’t start on a Monday, I have to incorporate some of the previous year into it. For me, 2025 starts on December 30, 2024. I usually start my yearly goals in the previous year just to get a running start, so it doesn’t really matter if a few extra days get into my journal.

If I have to deal with something that is on a month or quarter boundary, they are just a regular day in the journal. External deadlines can be on any day.

If this sounds good to you, you can use my 2025 Journal (PDF).