Exploring A Codebase

busypeoples profile image A. Sharif ・2 min read

There are many situations where we might get in contact with an existing codebase. Wether it being joining an existing product, working with a team to help with a problem or being brought in to conduct a code review or taking over an existing codebase from a different team.

What we see as developers is what other developers have written at first. We try to navigate through the codebase, try to get a better understanding of the overall structure. We look for things that help us to formulate an idea, like functions, like file structure. We look for quick indicators to help us evaluate the quality. We might try to identify patterns, we might be searching for consistency or for a README file. We might be trying to find the documentation, read through the doc blocks or search for other indicators.

Our first step is mostly to quickly get a better high level overview by trying to identify the architecture but also look at how code is structured to formulate a more concrete idea on the quality etc.

We have one advantage compared to the people that know the codebase: we can see it from a fresh perspective. On the other hand we also lack information and knowledge regarding historical context, workflow, the time constraints, changing team structure etc. We can’t tell if the product is driven by a concise plan or arbitrary and changing requirements. At least it’s very hard to understand at the very beginning.

Up until now, this is nothing new. Everyone enters an existing codebase differently, but what we mostly do is focus on the code and we mostly assume it has been written under perfect conditions. When we ask ourself: “Why is it structured like that, when it could have been implemented like this”, then we’re assuming ideal conditions but might also lack some context.

But if we take a step back and think about it from a different perspective, what else could we learn from an existing codebase? Maybe it’s good to ask ourselves some questions.

  • What where the conditions when the code was written?

  • Did these conditions change over time?

  • What role did product management or management in general play?

  • Was there time to talk about technical debt?

  • Was the initial design driven by a sole developer?

  • Are there any constraints or drivers that lead to over- or under-engineering?

  • Was there time to do some refactoring?

  • Did the scope change over time?

  • Who drives the decisions?

  • Who drives the timeline and scope?

The codebase will not provide all the answers to all of the above questions. But what it does, is to help us to move away from thinking that it’s only a developer’s problem. It’s helps us to move away from the idea, that developers are the only ones responsible for the code. Code is the result of different processes, people, collaboration, drivers and constraints.

What are your thoughts on this? Would be very interesting to read more insights and ideas regarding the topic.

If you have any questions or feedback please leave a comment here or connect via Twitter

Posted on by:

busypeoples profile

A. Sharif


Focusing on quality. Software Development. Product Management. https://twitter.com/sharifsbeat


Editor guide

I'm not sure sure I know the benefit. It sounds like these are questions to ask to stop blaming not necessarily understand.

The beginning of you post made me think of things I look for.

  • entry point
  • example usage
  • actually live functionality

The entry point is harder for libraries and frameworks. But the can provide the guidance on what happens.

Examples always provide clarity in what to expect.

An actual working example code is massive helpful and can get you the ability to learn with a debugger.

This morning I was looking through these tests which which look to follow the BDD test descriptions, I realized it was not helpful to understand the code.