How do you orient to a "new to you" code base?

I started at Forem in October 2021, and needed to orient myself quickly to a code base that powered sites much beloved by their community.

So, let's talk "How do you orient to a new to you code base?"

Comments

[SailzaNoel]

How do large code bases work ? manthrigam specialist in Chennai

[Jeremy Friesen]

i need to "see something concrete" and relate it to the docs. I cannot start with just reading the documentation.

Oh my heavens yes.

[Domi]

Visualize and investigate dynamic call graphs, data flow and more, using Dbux (self plug 🤷‍♀️).

[Tyler V. (he/him)]

I'm just here to ask what game the cover image is from? 😅

[Jeremy Friesen]

It's from cone.itch.io/hex-kit; I ran a Dungeon Crawl Classic's campaign and mapped the region using that tool. It's gorgeous and straightforward to use.

[Tyler V. (he/him)]

Thank you! Looks incredible 🥳

[Diego (Relatable Code)]

This can probably be broken down into several steps. Note I am mainly a front-end developer working with React/Typescript.

First step is to ask if theres a style guide or wholistic documentation for the codebase.

Then I'll just take a quick look at the file structure and the list of dependencies in the package.json. This will give me a good idea of what the overall flow of the project is like. This can be quite difficult if there is a ton of legacy code or unused packages, but atleast I'll know what is initially available to me.

As with all steps I'll take some notes down in Notion but this can be done anywhere. This is just to make sure it sticks faster. These notes will include naming conventions for the files, how things are typically organized.

Afterwards I'll just expand my knowledge as i work through tasks. Taking notes along the way of utility functions, syntax, practices implemented in the project. Usually I try to be conscious of only applying what I just said to more recent files. Its possible the codebase has differing styles depending on how old it is. But the newer stuff is probably more accurate.

And most importantly: i ask questions, and a lot of them. No company will expect you to be a pro in the inner-workings of the codebase on day one.

[Jeremy Friesen]

You have an admirably methodical approach, and it sounds like you generate documentation that helps grow your team.

[Atharva Shirdhankar]

When I started with Open Source Contribution. It was literally overwhelming for me to find the piece of code or file from the complete project which was needed to be fix or add new features.
But slow and steady I got used to it after 1 year of been an open source contributor . Now I can find the code and file which need to be fixed/add new feature.
The catch here is how I learned to get familiar with new codebase was been familiar with the tech stack the project is dependent on . I guess that's the fundamental thing.... according to me.
Cause whenever I tried to contribute to new codebase most of the time I came across new tech stack so I use understand that tech stack little bit and go ahead with contribution 😄.

[Jeremy Friesen]

Wayfinding in code-bases is very challenging. I know the Language Server Protocol is helping create an interface for code navigation via IDE-like behavior.

I realize that tree -d on the project root directory may yield tremendous insight into what's ahead.

[Thomas Hansen]

If the code base is written with high quality, your first place would be the folder system, allowing you to segregate into modules and logical components.

[Jeremy Friesen]

So, taking a step back, tree -d ./app (where app is the folder with the production code) followed by tree -d ./lib and tree -d ./test.

[tq-bit]

It depends

For every project, I try and follow this flow:

• Read the docs - get the most inconvenient thing out of the way first
• Read the specs or latest customer requests Try and understand: what's the goal of this software? what's the expected behavior?

Only when I grasped the fundamental idea, I start exploring the codebase, usually in this order (Example for JS Projects):

• Directory structure
• File structure

That's enough to get an overview. Next:

• Module dependency structure
• Architectural pattern (e.g. MVVM, MVC)
• Typings (if there are none, sometimes I create them myself with tools like JSDoc)

At this point, I usually grab the previous dev (if available) and ask him a few architectural questions.

• Why does class A use method X?
• What happened if I refactored function B into a util. module?
• What breaks if I change this data structure?
• Which dependant variables change if variable Z changes?

When I am able to apply the Software's goal to the code, I'm going into

• Class definitions
• Const definitions
• Environment variable definitions
• Function / method / class dependency structure

And then, sometimes I skip all of these and get to the last point:

• Change a variable that 'feels' important and see what breaks

That usually puts me into the position to start with change requests

[codewander]

Jump to the earliest commits, and try to see the big picture from the initial shape.

[Jeremy Friesen]

This is an interesting approach…see what the earliest intentions to get a sense for "Why did someone toil over this?"

[codewander]

I actually do it because people can only juggle so many concepts at one time, so the early commits representative the first developer trying to get something implemented, without the baggage of years of features and other things added on, so it is very easy to understand and see all of it. Then you can start to see traces of the early program when you look at the current state of a system.

[Jeremy Friesen]

Excellent software archaeology!

[Lucia Cerchie]

I used to diagram by hand to trigger my spatial reasoning-- still do sometimes. Recently started using codesee.io/ and I love it! It maps the codebase with dependencies for you and also shows you what files your PRs affect with a diagram.

[Patrick Wendo]

I will have to try this. It looks amazing.

[Jeremy Friesen]

This is a different approach than I'd considered. I think about how my change affects the call graph…but I hadn't given too much thought to drawing that graph.

(Though…as I type this, I have memories from decades ago of doing something like this. Hmm…a generous thank you as it reminds me of all the folks I worked with long ago. They are some amazing people.)

[Daniel Uber]

I definitely draw the call graph or a message diagram when there are more than 3 collaborators involved (which is perhaps the amount of complexity I can hold in my head at once).

My desk is littered with these things. I should make a little portfolio one day.

[Lucia Cerchie]

I'd love to see a picture!

[Daniel Uber]

this is on my desk now, it kind of captures (with bad light and poor penmanship) how the currentUser information is made available to the js frontend code in Forem (top left GET queries the database, right center is a local storage object, left center is a data attribute on the document.body, and the squares in the middle are functions reading and writing those values).

[Lucia Cerchie]

oh wow a peek into the inner workings! love it

[Jeremy Friesen]

One of my preferred methods of learning about a Rails application code base is to open up the app/controllers directory and start looking at files.

I do a quick visual scan of the method shapes; I’m looking at method lengths and widths, indentations, and syntax highlight. Looking for visual symmetries. In a way I'm looking at each controller as a visual painting.

Why? When I notice symmetry, it likely means that there’s consistency in approach. When it’s lacking, then I know that there’s a wider variety of approaches.

This process takes no more than 30 minutes. It gives me a quick sense of what my stewardship efforts will look like for this code-base.

Then, on the main branch, I run git log --pretty=oneline app/controllers. (Actually I run my own git-slog which makes it a more legible to me output.)

The git log gives me a list of all of the commits that included app/controllers. In a way this log is like listening to the highlights of the podcast produced by the contributors of the application.

Why the controllers? In my experience, these are the most contentious areas of a code-base. Which harkens back to the venerable "Fat Models / Skinny Controllers" conversations (put forward years ago by Jamis Buck).

[MiguelMJ]

What I did when I started working on this project on my company was to limit my work and understanding to the files they told I would have to work with. No need to know how the whole application works, only the files I would change. However, every time I needed to do something in other part of the code, I did some searches for functions I knew and tried to comprehend how my code was being called. With some time and some sporadic explanations from my coworkers I started being able to contribute to more and more code.
My experience is short and my beginning was slow, so in fact I'm not sure how I would do if I was required to handle the same code base but in less time.
But what I'm sure about is that I would do it little by little, I think there's no other way!

[Jeremy Friesen]

My experience is short and my beginning was slow, so in fact I'm not sure how I would do if I was required to handle the same code base but in less time.

I forgot to add my context, "I've been programming in Rails for 15 or 16 years." So I've accumulated a lot of visual indicators of code.

Your method, as someone with fewer years of experience sounds great. I hear a distinct "know my garden and get to know my neighbors" philosophy.

A few questions I have for you are:

• within this area you tend and toil, what are some patterns you're seeing?
• what code most recently surprised you, and why?

[MiguelMJ]

Know my garden and get to know my neighbours

Pretty much 😂

within this area you tend and toil, what are some patterns you're seeing?

I think this is somewhat broad, but I could say that the patterns I see are a product of the frameworks used. I've realized that they condition the code a lot more than I thought.

what code most recently surprised you, and why?

Negative surprise: to see how few regular expressions are used (in the code I see). I understand some people consider that they reduce legibility, which is reasonable. But, come on, I recently refactored 150 lines into 50 just by replacing nested if-elses comparing strings with a few short regexes.

Positive surprise: the bash script used to manage backend tasks. I didn't thought I'd get to see such a complete, flexible and organized alternative to third party tools. I definitely felt inspired when I saw it!

[Jeremy Friesen]

I love that you phrased this as "positive" and "negative" surprise. That's a very useful lens to bring to your job.

Regular expressions are a powerful and ancient magic. I always shudder when I see regular expressions that are not bombarded with unit tests. Because they can be challenging to write correctly; and once written challenging to explain as they are incantations of an alternate form.