Edition 4 - culture of writing readable and maintainable code

Hi ,
I think of the hygiene of a digital product like self-care. If it’s continuously ongoing you won’t ever feel the desperate need to drop everything and focus on it.

In today’s edition of LeadReads, I’ll talk to you about creating a culture where hygiene and sanity aren’t afterthoughts. It’s part of your team’s DNA.

Writing readable, & clean code

No engineer inherently wants to write dirty, unreadable, and unmaintainable code. It’s not an intent problem. The problem is not knowing how to measure the readability and maintainability of your code.

Processes, & frameworks are useless if your teams don’t know the why of it. If your teams don’t believe that doing it will improve the quality of the product and the experience of your customers even the best practices won’t yield results.

By focusing on the why, and the impact of processes we’ve created a culture where automation is second nature. We select the right tool for the intended outcome. Each engineer owns their features end-to-end. From writing them to ensuring that it always works. Not somehow, but always. Our open-source work is a testament to this.

I’ve created 4 broad headers. The need and use of each of them need to be championed by your team for this to work. Our job is to teach them how to fish and provide the equipment for it.

Here’s what it means in the Digital Product Development landscape

1. Using Static Code Analysers

Use a static code analyzer SonarCloud or set up your own SonarQube instance which enables readability and maintainability measures.

• Cyclomatic Complexity

  • measures the number of different paths through your code, helping you identify how hard it may be to test and maintain. Lower scores indicate simpler, more manageable code.

• Cognitive Complexity

  • gauges the mental effort required to understand your code, aiming to pinpoint areas that could be hard to read or modify. A lower score means the code is easier to work with.

2. Standardizing conventions

Standard conventions and practices enable better collaboration. You will no longer have PR discussions on variable naming conventions, unused imports, or other trivial items. Set up linters, and automated code formatters. Run checks as part of the CI pipeline.

Ensure that the reasoning for why you’re adding specific lint rules is clear.

3. The need for Deterministic Outcome

The only way of delivering consistently good results is by ensuring that you have a way of replicating steps and asserting outcomes. The more manual and longer it takes to do, the more friction is seen.

Automate it. Use unit, integration, e2e, & load tests. The goal for this exercise needs to be clear. It’s not to get more code coverage. It is to ensure your feature, product, and bugfix don’t misbehave later. Each engineer needs to use the right automation to ensure that their feature always works.

6 months later when the codebase looks foreign a missed case should break a test. It should act as the gatekeeper.

4. Having Checks and Balances

Have frameworks in place for feature flags, phased rollouts, monitoring & alerting with proactive reporting. This ensures a smaller blast radius for issues, faster turnarounds, and shorter SLAs.

This is the playbook on what needs to be evangelized and institutionalized even before you start writing the business logic. Your teams need to be on the same page about what Product Development means and it isn’t merely adding new features.

Until next time,

Mac✌️