I was in Bangalore this week for a client work and just, as usual, I decided to ask friends to meet up for lunch. Since Siddharth was back in town after his rather tiring trip we decided to catch up & exchange thoughts. We share a lot of common interests ranging from deep love of technology to make things which can create value for people, hence we often end up having deep conversations. I draw a huge amount of value out of these conversations, get my thoughts validated or at least boost my intellect. To pain a big picture, I try to surround myself with friends with whom I can have such conversations & they push me to be a better version of myself – I try to reciprocate the same for them.

Coming back to the subject of this blog post and why I'm so compelled to write about this topic.

While having a conversation we reached a point where we were discussing the importance of well structure codebases, to which Sid added: "Codebase tells a lot about a team".  This statement of his resonated with my experience on so many levels. The more I thought about it the more it made sense. My restless brain started applying this theory to all the encounters I had with codebases I've worked with in my professional journey starting 2007 circa and almost in all the instances I could connect back to the level of teamwork we had was apparent by just look at the codebase.

Looking back I can tell now – projects which had well-defined codebases were immensely productive, teammates had healthy work-life balance, business was growing positively because of fewer bugs which also meant happy customers. On the other hand, projects, where codebases were not mindfully crafted, was a chaos to work with. One could sense a constant pressure among the team members about what will break next, pulling in late nighters to keep everything in check, neglecting sleep or more important taking a toll on mental health and eventually impacting the overall business growth.

In software engineering, teams often obsess over scaling the code horizontally/vertically, they regularly invest a ton of time & effort reducing the no. of resources required to keep the code running, but, they almost never invest in scaling their own productivity.  Teams don't have answers to:

  • How much time does it take to set up a codebase for a new member?
  • Average commit to production time?
  • How trivial is it to introduce a change in the codebase?
  • Is the feedback cycle strong enough to help team members grow professionally or there is a culture of shaming team member for a making unintentional mistake?

I believe most of the team members do have an uncalculated answer to the above questions except they are never addressed mainly because oftentimes teams have a hard time correlating productivity to codebases, some of the teams have accepted this as a part of the trade & has blinded themselves to the suffering. On a side note, A team where ninja members are worshiped & learners are neglected should be called a cult.

One of the paragraphs above I briefly touched on downsides of badly designed codebases. Here are a few more impacts:

  • High churn in the team members working on the codebase.
  • Loss of respect amongst teammates resulting in a toxic work environment.
  • Common miscommunication between teams around expectation & delivery.
  • Lack of motivation to show up at work every day.
  • Fear of changing existing implemented functionality because nobody wants come as incapable.

etc...

Okay, I'm sure teams never intend to have badly structured codebase so...

How to fix the codebase

Fortunately, It is not difficult to improve the codebase. A big plus is most of the teams are so familiar with the drawbacks of their codebase – they will be able to quickly come up with a comprehensive list of fixes required. On top of that here are the few things I would suggest to aim for:

  • Reduce/Automate the no. of steps required to set up or get a project up & running to one single command.
  • Standardize development tools to a possible extent to keep team members code quality on the same level.
  • Regularly extract common part of the codebase in the form of libraries, packages, design system etc. regardless of a monolith/micro-service architecture.
  • Prioritise simplicity over complexity.
  • Documentation is a myth; code should be optimized for readability & expressiveness.
  • Learn from big open source projects about codebase structuring; they are usually nicely designed.
  • Make sure they are easily deployable.
  • Stick to industry-wide best practices rather than inventing own as they almost certainly lead to clashes.
  • At least shoot for having test coverage around critical part of the codebase (Remember: Do things that don't scale).

Overall, aiming for a healthy codebase is worth it; The payoff is huge in the long run which a team has to internalize sooner than later.

Do you agree with my opinions? I'd be glad to hear from you on this topic with an open mind.