Too Many Tacos

My editor of choice for a long time has been Vim. I recently switched to VSCode because of the improved integrations for work at my company.

The way I like to work is to have multiple splits open, with one file per split:

The Problem

I tried to get this workflow in VSCode, but it would open multiple files per split, with each newly opened file going in a new tab in the split rather than replacing the file in the split. This was really annoying. Closing a split required closing ALL of the file tabs that had accumulated in that split, and I would end up with the same file open in different tabs in different splits (I can’t get a screenshot of this unfortunately – for some reason I can’t get the original problematic behaviour back, which is almost as concerning as the problem itself).

The Fix

The fix was to enable the Enable Preview settings. I enabled them all to make sure I always get the same behaviour:

Here is the corresponding JSON:

{
  "workbench.editor.enablePreviewFromQuickOpen": true,   "workbench.editor.enablePreviewFromCodeNavigation": true
}

It’s one thing to read advice. It’s another thing to understand it and think about how to apply it. It’s hardest to follow it consistently.

My method for cementing a lesson in my brain: write it on the whiteboard beside my desk in my office. I end up looking at it on and off throughout the day. I take notes in Logseq for most things. This makes them organizable and recoverable. But when I’m trying to cement a habit, I write it on my whiteboard. Something like “When you’re intimidated by a problem, take a step back and break it down”.

I’m also trying a new thing: instead of writing it on my whiteboard, I’ll add it to my daily Logseq template so that it’s in my face all day (I organize my day in Logseq). I’ll report back on how this is working!

One of the most impactful work habits I’ve learned is to break up my work into a number of small independently shippable changes. It helps me ship faster, understand the problem better, and spread context.

Shipping small changes helps to clarify my thinking and make sure that I understand the problem. Because if I don’t fully understand the problem, it’s hard to break the work into small pieces that make sense. It decreases the number of changes on my working branch, meaning that I have to hold less context in my head, and rebases are quick and easy. It makes it easier to write detailed pull request (PR) descriptions, because I’m only describing a small change. Since I need to write a larger number of PR descriptions, I get practice explaining the context around the problem, which can help me spot errors in my logic and understand the problem better.

It decreases the time amount of time taken for reviews: small changes are easier to understand and less intimidating to review, so reviewers are more likely to review them right away, in a single sitting. Because reviewers can understand my change, we spend less time going back and forth on little details and more time discussing the actual problem. Since reviewers have an easier time understanding the change, and can give more useful feedback, it is less likely that a major problem will escape notice.

Less time goes by between PRs, meaning that reviewers can keep the context in their head. This increases the speed and quality of code reviews. Shipping a large number of small changes is almost always faster than shipping a small number of large changes.

Shipping more stuff also just gives me more little dopamine hits and a sense of progress that makes me happier.

I keep my changes small not just by planning out my changes beforehand, but by continually looking for pieces I can carve out from my working branch to ship independently. For example, if I need to move a duplicated testing method into a shared helper, I’ll split that off from the current branch and put up a preliminary PR for it (small refactor PRs like this are easy and fun to ship because there usually isn’t much to debate about). Then I’ll go back to my feature branch and rebase on the preliminary refactor branch and keep working while I wait for reviews.

So next time you find yourself hunting down reviewers or feeling nervous that your working branch is getting big, take a step back and ask yourself if you can split up your changes.

Bike shedding is a real thing. I think about it a lot when reviewing code. I try to see the big picture and ignore small nitpicks in favour of reviewing the overall architecture and intent of a change.

But sometimes feedback you might think of as bike shedding is actually super useful. One of these cases is when it takes a while to understand the code. If it is hard to understand someone’s code, it can be tempting to think it’s a problem with you (oh, hey there imposter syndrome!): maybe you’re missing context, or you just aren’t smart enough.

I say no: as a code reviewer, you are closer to the problem than anyone else who reads this code later. Assuming there is an adequate PR description, and you read it before looking at the code, you should have more than enough context to understand the code without needing to re-read it twenty times or ping the author directly for an explanation. Someone who comes across this code a month, a year, or 10 years later (including the author themself) will definitely have a far harder time than you are having now, so do that person a favour and call it out!

If you find yourself reading and re-reading code during a review, let the author know that it was hard for you to understand! They may just have been working on the problem for a while and didn’t realize how it looks to someone lacking their expert context. They may have tried to simplify it and couldn’t figure out a way. Maybe the solution is as simple as improving the PR description (I think a detailed PR description documenting the context around a change is a great way to communicate context). Maybe it’s as simple as making the code more verbose. Regardless of the solution, if you’re having a hard time reviewing someone’s code, that is always great feedback.

Some examples:

• “I had a lot of trouble understanding what is going on here. Could this be easier to understand if we broke this branch condition into multiple variable assignments?”
• “It took me a long time and lots of jumping around between files to figure out what is happening here. Is there an abstraction that could make this easier to understand?”
• “I’m not sure what is happening here. It looks like <…>. Is that correct? Maybe I’m missing some context”. If it turns out that you are missing context, you can suggest updating the PR description.

No matter what, make sure to always assume positive intent, and leave comments with positive intent! We’re all doing the best we can!