Author Archives: Lou Franco

If you still have nitpick PR comments

This is part of a series on reducing PR code review time, which is important because long feedback loops are one of the drivers of low developer productivity. Here are the other articles of the series with a TL;DR to remind you of the key takeaway, but there are details in the article of how to do it.

If code reviews take too long, do this first (TL;DR: gather data)
What to do about nitpick comments in PRs (TL;DR: eliminate them)
What to do about excessive (good) PR comments (TL;DR: make better PRs)
Not all PR nitpick comments are bad (TL;DR sometimes you need or want them)

If you are still getting nitpick comments after you have done what you can to eliminate them, try adding a checklist for comments. Here’s an example checklist to start from:

Is it a bug?
Does the code violate the specification?
Does the code violate our design system?
Is the code reimplementing something where it should reuse our library code?
Does the code not meet our style guide?
Does the code not meet our testing code coverage requirement?
Is the code not consistent with the vast majority of our codebase (especially recently approved code)?
Does the suggestion have an obvious, objective way to resolve it?

If a suggestion doesn’t meet your criteria for a good comment, then try one of these techniques to improve the comment

Reframe nitpick suggestions as an (objective) defect with a clear way to resolve it. So, for example, if you “don’t like” a variable name, give a reason why you don’t like it. Some examples that are actually defects: (a) the variable is two letters and you have a standard that requires four or more (b) the variable doesn’t match your naming convention (for example, you always use the word “count” instead of “length”) (c) you don’t understand the variable name — suggest better names — express how the name is confusing you, which is more objective than “not liking a name”.
Reframe the suggestion as the beginning of a process to update coding standards. When new non-defect, but possibly good comments are warranted, they should start as suggestions that might change the coding standard. In this case, you are going to move the discussion to what ever process you use to change standards (e.g. a retro)
Make the comment if we are in a situation that warrants it anyway: See Not all PR nitpick comments are bad

If the suggestion is still nitpick that you can’t improve, and it isn’t warranted anyway, don’t make it.

Not all PR nitpick comments are bad

This article is part of a series on reducing code review time. It helps if you have read these two first.

If code reviews take too long, do this first (gather data)
What to do about nitpick comments in PRs (eliminate them)

In the second article above, I define a nitpick comment as one that is just an opinion and not a defect, where a defect is something that doesn’t meet some objective criteria. A bug is an obvious example but so is a style-guide violation. A nitpick is a comment where the author and reviewer might disagree, but the issue isn’t objective, and there isn’t an obvious way to resolve the problem.

I recommend that you have almost none of these kinds of comments in a review, but there are a few cases where it’s ok.

During onboarding: You should set the expectation to your new hires that the first month or so of PRs might have excessive commenting as a way of training on culture of the team. To make this less onerous, early PRs should be very small. The more junior the new hire, the longer this might last.
If requested: Sometimes we are really do want to ask for opinions on code that isn’t ready for merge, but you want more eyes on it. In that case, authors should tag their PR as something that they would like more help on, and then any suggestions are fine. Authors that are doing new things in the codebase (and possibly setting new standards) should proactively request (nitpick) opinions.
As a precursor to setting a standard: if you have a strong opinion that you think should become a team standard, then starting the conversation in a PR comment might be warranted. I would recommend that you quickly move it to whatever process that your team uses to change their standards (e.g. a retro). Use the PR as an example.
If rare: If you think it won’t derail the PR and that the author would welcome it, then go ahead. A good example is pointing to an interesting technique that the author might not be aware of, but you think applies. This is more of an FYI than a request to change something.

What to do about excessive (good) PR comments

This post is part of a series on reducing the time it takes for a PR to go through code review. Here are the first two articles:

In step 1, we gathered data, and in step 2, we took steps to eliminate nitpick comments. But, we could still have slow code reviews because there is a lot of discussion about the pull request that needs to happen before the code is merged.

Some of this is fine. There will always be outlier pull requests that merit careful attention. However, if this is the norm, then it’s worth taking steps to reduce the code review feedback loop because (according to DevEx) long feedback loops are one of the drivers of low developer productivity.

When you have a lot of good commenting on a PR it might be a sign that the author isn’t checking their own code enough before they create the pull request. Spending an hour or so making sure that a pull request doesn’t have obvious problems saves the time of the reviewer but also reduces the feedback loop, which could go over several days.

On my team at Trello, almost all PRs were approved within a day because we had a culture of making sure that PRs were easy to review. I have documented some of our practices here:

To construct a PR that is easy to review, the code must be correct and also easy to know that it’s correct. Here are some ways to reduce the time it takes for reviewers to approve PRs:

Use automatic linters and code formatters that make it impossible to PR code that doesn’t meet your coding standards. The reviewer doesn’t need to check for style problems as they are impossible.
Go beyond simple automations. Automated review tools exist for accessibility, security, code coverage, static analysis, etc. These should establish a baseline to assist the reviewer and not replace them. Reviewers should not look at PRs until they pass the automated checking.
If you can’t automate something, create a short checklist for the author to go through before posting the PR.
If it’s clear that a PR has lots of problems, a lead should have a 1:1 with the author to train them on self-checking and pair program a better PR with them. This avoids back-and-forth that might take days. The goal should be to get the PR into a state that the lead would approve.

When PRs are slowed down because of excessive back-and-forth between the author and reviewer, but all of that discussion was necessary, that is an indication that not enough work is being done by the author to make the code obviously correct. Don’t discourage the commenting or short-cut the review in this case.

What to do about nitpick comments in PRs

In “If code reviews take too long, do this first“, I said that the first step was to gather some data on your code reviews to identify pull requests that take longer than your goal time. One common reason I have seen is that code reviews take too long because there are excessive small, unimportant suggestions.

Not all small and unimportant suggestions are bad. The problem happens when a it’s just an opinion and the code isn’t objectively wrong. So, for example, a typo in a code comment is worth pointing out because the author can fix it without further questions, and the comment is improved. Another example is a clear violation of the style guide, like using a variable with underscore separators when your standard is camelcase. In these cases there is no argument that the original code is correct, and it’s trivial to fix and recheck.

But comments that are just an opinion like: “I don’t like this variable name” or “you could use map() instead of iterating the array” or “this function is too long” are a matter of opinion in most cases. It’s not as clear what to do about it and might end up causing some more conversation. The author’s second try might also not satisfy the reviewer. If this code was clearly wrong, that would be fine, but it’s not worth the extended time to fix a difference in opinion.

To address the problem of excessive nitpick suggestions, the team should adopt a standard that a PR comment should be pointing out a defect. Here is a short list of some obvious defects:

An off-by-one bug in a loop
The screen doesn’t match the specification
An error case is not checked
Typos in variables, function names, or comments
Using tabs when team standard says to use spaces (or vice versa)
Putting business logic in a view when the team requires an MVVM pattern
The code reimplements a function when it should use the one in our shared library

This is not an exhaustive list, but the pattern should be clear. A comment is pointing out a defect when it can compare the code to some agreed upon requirement or standard. It’s also clear what to do about it, and that it must be done.

So, if you find in your data that you have a lot of nitpick comments, gather them all together and go through each one and categorize them:

OK: If the comment is pointing out a clear defect against an agreed upon requirement, then that’s a good comment, and the problem is not the comment.
To document: If the comment is not a defect, but you think the comment is good, and there is a pattern of this kind of comment, then maybe this belongs in your coding standard guide such that it’s clear that the code is defective and what exactly to do about it. After this is documented, future comments of this nature are OK.
To eliminate: If the comment is not a defect and you don’t even think it should be a standard, then this comment should never have been made.

After doing this step, in the future, most comments should be OK, and sometimes there will be a comment where it’s unclear whether it should become a new standard or not an acceptable comment. Things like that can be hashed out using whatever process you have.

It could still be the case that there are too many comments and that is still the main reason that code reviews are taking too long. In the next post, I will explain what to do about the problem when you have too many good comments on your code reviews.

Seven Years of Slow and Steady Progress Towards 30×500

I just looked it up—I enrolled in Amy Hoy and Alex Hillman’s 30×500 course in 2017. The course teaches their technique for starting a small subscription-based business that gets $30/month from 500 customers. 2017 was also the year that Atlassian acquired (my employer) Trello. Since I was locked into a 4-year vesting period, and I wanted to work at Atlassian for at least that long anyway, I was never going to start a business right away. But I thought it would be a good idea to lay some groundwork so I could be ready whenever I decided to leave Atlassian.

The first step in 30×500 is to pick an audience—ideally one that you are a part of or that hires you. I picked iOS developers. So I started adding educational content to App-o-Mat, a site I started a few years earlier to build on my book, Hello! iOS Development, but that I had neglected. With this newfound focus, the posts I wrote in 2017 helped me become a more frequent contributor (and editor) of the mobile section for Smashing Magazine. The money I made from Smashing paid for the 30×500 course several times over, but it was hard to keep writing and also excel at my day job, and so I let the writing wane over the next few years.

In 2021, after I resigned from Atlassian to go independent, I decided to get more serious about applying 30×500 techniques. I concentrated on WatchKit and Workout tutorials because I could repurpose what I had learned writing Sprint-o-Mat. But my consulting business became more software business coaching and less programming, and I realized I wasn’t really in the iOS developer audience any more. So, I started searching for a new one.

I got serious about writing educational content along a lot of different dimensions including software (of course, but more like what I was consulting about), but also job searching, personal finance, and writing. Over the next couple of years, I wrote hundreds of posts. Looking them over at the end of 2023, I realized that I had a lot to say about technical debt.

At the beginning of 2024, my goal was to write a small (50 page/10k words) e-book—more of a pamphlet—on technical debt. This led to a guest article on The Pragmatic Engineer (so I was continuing to get paid to write). Mostly, I treated this as signal that that the content was useful. But the article helped me build an email list and led to podcast invites and webinars, and the content grew based on what I was being asked about. Last week, I sent a document with 40k words to my editor—my hope is that it will be ready to publish by Q1 next year.

So, here I sit, seven plus years after I took the 30×500 course—I still don’t have even 1 of the 500 paying me $30/month. However, the course long ago paid for itself in direct dollars for my writing and easily 100x in terms of the consulting work the writing helped me land and service. The secret sauce of their method leads to finding an endless supply of topics to write about. Honestly, I barely do it right, but just going in the right direction has been good enough.

It helped me develop enough content for a book and the seeds for a few more. I do think there’s a subscription business here. Or maybe a YouTube channel? Or maybe just what it is so far: a blog, a podcast, a book, a source of leads, and proof to myself that I’m a writer.

Book Title as Visual Metaphor

I’m reading a book called Nonfiction Alchemy [affiliate link] by Jordan Ring that has some advice on finding a voice. A lot of it resonates with what I wrote in Writing as Yourself to Yourself. For example, in a section called Write with Heart, he advises you to “write like you speak” to find your voice, to tell stories because “they bought your book, not someone else’s”. But the part where he talked about his title and his voice was something I had not seen before:

I debated writing a more streamlined “business type” book with an unoriginal title like “Write Your Damn Book!” I thought about using straightforward chapter titles and letting less of my personality shine through. I summarily shut down this line of thinking.

He goes on to talk about how the word “Alchemy” is evocative and that he is using it to find other (more original) words to describe his ideas. He talks about spells and potions and elixirs, and it just makes the prose more enjoyable, original, and memorable.

It reminds me of an exercise from Writing Down the Bones by Natalie Goldberg [affiliate link]. I talked about it in my podcast episode, Finding Nouns and Verbs. Here’s how I described it:

Take out a piece of paper. Divide it into three columns. In the first column, write down any ten nouns. Then, fold back it over so you can’t see those nouns and look at the second column.

At the top of the second column write down an occupation. She gives examples like chef, pilot, or doctor. Then, for the occupation that you chose, list all the verbs related it. In the book, Goldberg picked chef and then wrote down cut, slice, fry, marinate, bake, boil, etc. Write down as many as you can think of. You don’t need to limit yourself to 10. In fact, try to come with a lot more than 10.

Finally, open up the paper. Now you can see both columns. A column of nouns and a column of verbs. Pick a random noun and then find a verb to go with it and complete the sentence.

This will get you thinking of and using concrete and specific nouns and verbs that exert themselves to describe your scene. You won’t need to rely on adjectives and adverbs as much, and when you do, they’ll have more impact.

Thinking along these lines, with my title now Swimming in Tech Debt and the central metaphor being a swimmer trying to go upstream and being thwarted by debt. In my book, I show how to use the existence of tech debt as a way to propel yourself. The payment of the debt gives you energy and joy that puts you in the flow and makes you go faster. Even the word “flow” serendipitously is related to swimming and probably belongs in the subtitle.

Using the Goldberg technique, I could make a list of verbs that describe what a swimmer does: stroke, push-off, flip, wade, coast, kick, etc. This is of course, a good use of ChatGPT, which is a kind of super-thesaurus. It says: Swim, wade, stroke, paddle, dive, float, glide, submerge, surface, tread, splash, flip, scull, plunge, sink, kick, sprint, roll, breathe, and relax.

The idea is to use those words in the text sometimes instead of the obvious one. Enough that it brings some life to the text, but not so much that it seems like a gimmick.

Titling a book

The working title of my book has been Pay Tech Debt to Go Fast Now. I chose this because it’s the short answer about what I think you should do if you have a lot of tech debt, which is to concentrate your payment efforts on short-term developer productivity. The book is the long answer with lots of recommendations of how to do it.

But, I haven’t been satisfied with it as a title. There’s a passage in my book that seems to have resonated with a early readers, and I’m using that as a signal that it would be a source of a good title:

It’s been hard for me to talk about technical debt outside of engineering. The problems we tackle only exist inside the codebase, which is invisible to stakeholders, but it’s the water we swim in.

I don’t know how to explain that to others that don’t live in water. To us, working in a codebase with a lot of debt is like swimming upstream. It resists us moving in the direction we want to go. We eventually get there, but everyone else just sees the result and doesn’t feel the resistance. If we are slowed down, it just looks like we’re slow swimmers.

In the Write Useful Books, Rob Fitzpatrick recommends making a promise to the reader and putting it on the cover of the book. He says that it could be the title or subtitle. I overindexed on how good “Write Useful Books” is as a title, which is how I ended up with mine. But, I think it breaks down when the promise can’t be short. I think you need something easy for someone to remember and recommend. Pithiness is important.

I am also reading Nonfiction Alchemy [affiliate link], and in it Jordan Ring talks about having a central metaphor to use as a source of vocabulary in the book. “Alchemy” is his example, and the chapter titles are drawn from the same metaphor. I’ve been thinking about that idea too.

Yesterday, I was in Barnes & Noble and just staring at the non-fiction bookshelves with my wife and was telling her about this problem. We kept throwing out terms and while we were there, she came up with “Escaping the Tech Debt Trap”. I like “trap” and one of my favorite books is The Pleasure Trap [affiliate link], so I was drawn to it. I tried to think visually about the idea of a trap.

Then, I remembered that “swimming” passage in my book and thought about swimming in a river and going upstream because I needed to get somewhere, and how I could use the obstacles as a handhold, and push off them to propel myself. The visual helped me realize the physicality of my recommendations. Then, I thought of the title Swimming in Tech Debt, and I liked that it had a double meaning. There’s a play on words that sounds like it could mean something similar to “drowning in tech debt” (being overwhelmed), but what I mean is how to get through it, how to swim through it.

So, anyway, that’s the new title.

If code reviews take too long, do this first

Short feedback loops are one of the drivers of productivity according to the DevEx model. On my team at Trello, we had a goal of all reviews being done inside 24 hours. Having that goal drove behaviors that made most reviews complete in a few hours. So, to start, collect data and get on the same page.

If your reviews are taking too long, try these enabling steps first:

Gather metrics: If you use GitHub, try this repository metrics script to get a baseline.
Get consensus: Nothing will happen unless the whole team is on board with this being a problem and that it can be fixed.
Set a goal: I know from experience that 100% of reviews in less than 24 (work) hours is possible. If that seems out of reach, set something that you could accomplish in a quarter.
Inspect outliers: Treat outliers like you would treat an outage incident.
Compare reviews that met the goal to ones that didn’t: Gather statistics about PR’s and see if you can find differences between the ones that did and didn’t. For example: number of lines changed, the author, the reviewer, the number of commits, the part of the codebase, etc.
Put real-time monitoring in place: If you are the lead, just do this manually to start. At the beginning of the day, make sure all of yesterday’s PRs are going to be reviewed soon.

Tomorrow, I’ll write about some common problems and what to do about them.

Network with Alums Just Ahead of You

Yesterday, I wrote about using your alumni network to make you more lucky. In most of my stories, the alumni network that was most helpful were in my year or just a bit older. They are the ones that just got a job and know what works in the current job market. They are also the most like you, so their advice is relevant. And, they know you, and like you, and so they will want to help you.

When I talk to my mentees, I keep warning them that my information is way out of date. I got my first job by looking in the classified ads in a newspaper. That ad led to a recruiter that placed junior software developers. Those parts of my story are from olden times.

But, networking with your college classmates is evergreen. The easiest way to do this is to just be a good classmate, study partner, and extra diligent when working in groups.

Alumni Networks Increase Your Luck Surface Area

When I walked into the second interview at my first job, one of the developers said: “Hi, I think you know my husband.” It turned out that her husband was a college classmate of mine. I didn’t get the lead from him (that would have been smart of me), but at least he must have said nice things when she asked (or I’m guessing I wouldn’t have been hired). It was pure luck, but I’m a big believer that Randomness is the Great Creator.

The woman who would become my wife started at that same company two years later. She was smart enough to get a referral from her alumni network, who had also gotten the job through an alum connection from a third person who had worked her alumni network to get the job through the wife of one of our executives. It was a triple-bank shot, with absolutely no chance of working, but without it, I would never have met my wife.

My luck continued. At my next job, I helped find one of our early customers, who was a prominent alum I had met because he hired a few of my friends (fellow alums of both of us). The work we did for them eventually led to a patent and getting VC money to pivot to a startup. This was more than 25 years ago, and I am still on the board and participating in their successes. More than 90% of my 2024 income came from connections I made there.

From the outside, it looks like randomness, and it is, but there are things you can do to move the odds, and networking with alums is an easy one.