Your codebase as a product

The end goal is pretty simple, to increase motivation by nurturing a codebase that invites you to work in it.

It can be an energy sap to work in a codebase that’s got lots of cracked windows & friction to getting work done.

The more points I wrote down, the more this felt like yet another dx chat. lol.

User-Centric design

Borrowing from Tony Ho Tran, User Centric design can be summarised as:

  1. Identify the users’ needs and the context around them.
  2. Specify requirements for both the business and user.
  3. Design solutions

The same philosophy can be applied to your codebase.

Iterative improvement

  • Regular, little refactorings, see tidy, first?
  • Iteratively based on user feedback
  • Iterating based on improved mental models of the problem & solution

Feedback loops from users

Regularly interview, poll, & survey your developers in order to find pain points & desired features in their development workflow. Make sure to actually action out stuff based off the feedback if you don’t want to see engagement fizzle.

Feedback loops from machines

Similar to regression testing your product, your codebase can be given the same treatment.

The general idea here is to establish an acceptable quality threshold, & use static analysis to keep your code quality above desired thresholds at all times.

Here’s how I like to build code quality feedback loops into my workflow:

  • Github actions on push/PR to main
    • Lint check
    • Type checks - does it compile?
  • Notifications on mobile, that way any problem is surfaced early

Documentation

  • Architecture
  • How to fix common issues

How I like to do it:

  • Keeping .md files in the codebase
  • Following the high cohesion folder structure, I like to have these markdown files closet to where they’re relevant.

Documentation and self-service tooling are products, and they thrive under the same regime: sit down with some teams and watch them follow your instructions, then improve them.

Get the boring stuff right

  • Cohesive folder structure

Onboarding

In an ideal world, products have a well thought out and streamlined onboarding process. You want the same experience for your codebase.

My new gold standard for a good dev onboarding process is a new dev should be able to make their first productive commit or pull request on day one.

Analytics & metrics

There’s no shortage of analytics & metric frameworks for SaaS products. I’d say you can do the same for your codebase health.

meme

  • Space & Dora
  • Change failure rate
  • Mean time between failure
  • Products like linearB can help
  • Read Accelerate

The true test of good code is how easy it is to change it. Martin Fowler, Refactoring