A simple self review habit that converts some “unknown unknowns” to “known unknowns”. Leverage text search to find related code in a codebase too large to memorize.

The Habit

Before I open up my pull request and ask colleagues for feedback I like to take a step back and review it myself. The so called self review checklist.

I’ve come to like a remarkably simple item on that self review checklist so much I nowadays tend to do it a couple of times during actual development and not just at the end.

I call it “Text Search to Widen the Gaze”.

Just look at the git diff, choose a couple of key parts of the code, and text search for them in the whole code base of your company.

Surprisingly often this leads to further insights. Such as:

  • There is duplicate code you should update as well.
  • The bug you are fixing exists in another few places.
  • A colleague already coded something similar and you should likely talk with them.

Example

You are a Java backend developer currently collaborating closely with the React frontend team, building the endpoints they need for that new frontend app.

One of the endpoints returns a list of images to show in the frontend and the images have names:

The frontend team are asking you to alter the sorting in the endpoint. They want the images sorted by name but in such a way that “Image 10” and “Image 11” appear at the end and not after “Image 1”.

After some Googling you find a couple of articles on the subject

and an open source library implementing this so called “alphanum” or “humans natural” sort: https://github.com/gpanther/java-nat-sort

You add the dependency to the pom.xml

and rewrite the following old code

into this new code

Before opening the pull request you choose to widen the gaze using text search.

You first choose some interesting text to search for based on exploratory questions:

Question1: Is this Maven artifact already used elsewhere?
Text: <artifactId>natural-comparator</artifactId>

Question2: Is some other implementation of the algorithm used elsewhere?
Text: NaturalComparator
Text: AlphanumComparator

Question3: Are there other sorted streams that would be better of sorted with this comparator?
Text: .sorted(Comparator.comparing(

Finding1: It turns out another team on the company uses this Maven artifact extensively already. You choose to go talk with them for a bit about the pros and cons of this library, and the result is they will talk about this kind of sorting on the next guild meeting because it’s useful and oddly enough is not included in the JDK or Guava.

Finding2: It also turns out that another team is using another implementation of the algorithm. That one does not support cases insensive sorting though and they copied the java class into the code. The result is they will switch over to the maven library you found because they think that seems better.

Finding3: Finally you find another three places where sorting should likely be done using this comparator. You ask the frontend developers if it would be good to sort these too and they say that yes, that would make a lot of sense. You scope up the ticket slightly to include sorting in these other few places.

To Onboard Yourself

This habit can be really helpful when onboarding yourself at a new job. You get to see other parts of the codebase and you will have seen the code for a reason, making it easier to remember. You might also find good reasons to talk to colleagues, perhaps even in other teams than your own should you wish for it.

I suppose it can also be useful for real veterans at a company some times? Especially if the company is large and the code evolves fast.

To Go that Extra Mile

While this habit might seem like something that will just create more work for you I think that’s a short term effect. Long term it’s a time time saver if done right.

If you did just what the ticket said, then likely another three similar tickets will be written over the coming months, and you could have predicted that and saved your team mates some time.

The idea is not to dive deep into the rabbit hole or conduct endless yak shaving. The idea is to scope up the ticket just a little bit so that it’s not just narrowly the ticket at hand. This will help you feel ownership for the company codebase and seem a more responsible developer.

It also opens up these interesting conversations with colleagues about best practices where synergy is built and knowledge sharing happens.

#and-so-they-all-lived-happily-ever-after

Enjoy! \:D/