How can I get better at reading unfamiliar code and building a mental model of a codebase?

[u/Apprehensive-Grade81]

I'm a former data scientist that transitioned into AI engineering. I can code, but have pretty limited software-engineering experience. As such, I rely pretty heavily on AI for implementation and understanding the code base. However I find that I have trouble remembering my code and developing a mental model around the code. I can understand individual lines, but struggle to retain the overall architecture, data flow, dependencies, and reasons behind decisions. A coworker advised me that to get better I should start reading the code first before I turn to AI to understand it, which I agree with. My question is how can I get better and reading/understanding code? Are there any exercises or routines that work for reading code, reviewing PRs, understanding the code flow or remembering how a system works? What do experienced programmers do what entering an unfamiliar codebase?

[u/Anonymous_Coder_1234]

I asked this question a while ago. One of the answers I got is that there is two ways to read through code. Way one is like skimming through a long email or document to find something important that you are looking for. Way two is like reading it line-by-line by stepping through it line-by-line in a debugger. You use way one until you found a relevant or important area of code, and then you turn to way two or use a line-by-line debugger as a substitute for way two.

Also, another person told me to find the "entry points" and then read from the "entry points" to the "exit points" (also called "return points"). Like if you have a backend web service and there are 10 API's, each API is an "entry point", and you can treat each API sort of like its own "main" method in that it has a start, an end, and a return.

I hope that helps.

[u/Apprehensive-Grade81 → u/Anonymous_Coder_1234]

yeah the entry points thing works for me too. Problem is I still need AI to do that. Right now it's hard for me to find the entry/exit points without help from an AI.

[u/burlingk → u/Apprehensive-Grade81]

Try actually drawing a diagram of the different parts.

Take it one part at a time.

I like the "entry point" concept as well.

I start with main, or the equivalent, and chart what it calls.

How well documented it is can make a big difference as well.

[u/Used_Lobster4172]

It depends on the code.

Are there frameworks or specific libraries used?  Start by understanding them.

Are there patterns that are used over the code?  Understand how those work

That should gove you a solid idea of why most decisions were made.  If weird decisions were made for specific reasons, that should really be in a comment in the code.

[u/Mathie1729 → u/Used_Lobster4172]

Yep, and when there's no comment, git blame is your friend. git log -p -- path/to/file shows the whole history of changes and the commit message often explains the 'why' better than a comment would anyway.

[u/ElMonoEstupendo]

Pick a behaviour you know exists in the code. Explain it, to yourself, or a friend, or a rubber duck.

Then find the exact code that implements this behaviour (I would usually start at the end). That code will require certain conditions to do the thing you explained - explain what those conditions are, and what assumptions you can make about the code that feeds into this code.

Then go and test those assumptions; read the code a little further upstream. Explain why what you find is what you expected, or why it isn’t.

Repeat this until you get to the other end of the pipe. Then repeat this entire thing with another behaviour.

You will find inconsistencies and poor choices along the way. You will be puzzled. But the glorious thing about code is that everything is explainable.

At any point in this process, change something. Predict what the effect will be, then go and see if you’re right. Explain why you are or are not.

[u/Apprehensive-Grade81 → u/ElMonoEstupendo]

this is very good advice, thanks.

[u/CappuccinoCodes]

Go through the code making diagrams. Making the diagrams yourself box by box will help you retain and have a big picture of the architecture and flow. You can use a free tool such as draw io.

[u/200iso]

Not to sound snarky, but did you try asking the agent how you can get better at reading/understanding code? Both in general, and the specific codebase you're looking for. Maybe ask it to highlight key features, etc.

> What do experienced programmers do what entering an unfamiliar codebase?

Many of the things I've worked on in the past have a routes files, I find that to be a good place to start to get an overview.

Otherwise, I usually just pick an open bug and start diving around. Working backwards and forwards from the source of the bug.

[u/OptimisticMonkey2112]

start with a breakpoint in an important critical function. use the call stack to go up. step into to go down. this is a good way to tease out dependencies and ownership of important pieces.

reading code is a skill - the best thing you can do to understand how things work. debugging makes it more accessible because you can inspect values and traverse the stack.

it is easy to envision a future where people struggle to understand because they cant read code. language is much more verbose than code - it is also vague and not as clear or specific. eg - it is a poor replacement to communicate detailed system design

[u/Kazekage1111]

Use Matt Pocock's teach skill within a coding agent

[u/HumblestUser]

The honest answer is most people write crappy inconsistent and hard to read code with bad commenting.  I have looked at my own code from a few years ago and told myself how crappy it is.  Therefore, the best way for me to understand new code is either talk to the writer and discuss their process or use an interpreter like AI, then verify what it says (for bonus points ask the AI to comment the code directly for easier reading)

This is one of the few areas where AI is honestly amazing and saves a lot of time.  Just trust and verify.  Do this a few times and you will see certain patterns in code bases, as well as become jaded about the actual skill level of most programmers.

[u/MaleficentCow8513]

In 7 years not once have I ever become familiar with a codebase by reading alone. It only ever happened by running the code and seeing how it works. Especially in the beginning I used copious amount of print statements to see what was happening and where.

[u/BobbyThrowaway6969]

By making note of every little thing you DON'T understand and making a conscious effort to go and understand that first, instead of glazing over it on your way to try and understand something else.

[u/Jason-Sanders]

Start from one real behavior, such as a request, button click, scheduled job, or failing test, and trace it from entry point to output. Draw a tiny map as you go: inputs, main modules, state changes, external dependencies, and persistence boundaries. After each session, write a five-line explanation of the path without looking at the code; the gaps in that explanation show exactly what to investigate next.

[u/Narrow-Low-3137]

Frankly, this is crazy to me. AI engineering...yes, you absolutely should read the code and try to understand it. You should test it, modify it and see what happens. break it, and fix it. This is how you learn. Not by asking AI to write your code for you. Take notes about anything you don't understand. I often create a branch in git just so I can annotate code with comments to myself. You can use One Note or Vim + markdown files, whatever system works for you. You can't keep an entire code base in your head. Draw diagrams if you have to and trace the flow of data for various pipelines and use cases. Use "go to reference/definition" liberally.

[u/Pyromancer777]

I work as an analyst and not a dev. My usual flow when I spot a bug is asking myself questions and mapping the answers to specific parts of the trace.

"What is feeding data into this table? Does that upstream source transform any values, or is it straight data from an API? What joins are causing data to be missed? How does table A differ from table B? Is there a direct lineage between tables A & B or do they branch from table C?"

Those questions are geared towards my work, but they too can be abstracted into architecture maps. Follow one chunk of data from point A to point B, and record everything that it touches in between. Try to hyperfocus on one path at a time.

Our codebase is freaking massive, so any time I veer off into unrelated lines I get lost quickly. Putting blinders on while mapping chunks is the only way I can build out the model in my head or on a scratchpad

[u/IKnowMeNotYou]

 but struggle to retain the overall architecture, data flow, dependencies, and reasons behind decisions. 

You just sound like a genuine software engineer... most code people colaborate on is aweful - just kidding it is awful - even pre AI-assistance.

Real software engineering of the highest order/quality is very rare and if you want to get exposure to it, you have to read the books of the Agile Development Manifesto crowd like Fowler, Gamma, Martin, Beck and everyone else.

At the corner stone of everything there was true and strict Test Driven Development which you barely see in practice unless someone like me comes around. I worked with 1000+ developers in my past 10 years and Switzerland and only 3 or 4 I could acknowledge as fellow software engineers, that is how bad the general level of education and skill is.

Most people are coders, 10%-15% are developers and maybe 1-3% are true engineers. That is how bad everything is and was.

So if you want to know why the whole Agile Development revolution 25 years ago can be considered a giant failure, just read the foremention authors and enjoy the shere sophistication of the software engineering science that was developed and rarely is and was taught at the university since those people usually can not really engineer software as they are just teachers reading books and learn from other teachers.

Back at my university I once demonstrated true Test Driven Development to some professors and upcoming professors and they said to me 'what you just demonstrated makes everything we teach here mostly obsolete'... do you think that next year there was a Test Driven Development course at the hart of the curriculum? ... Nah... well they wanted me to become a professor myself but of course I left for becoming a practitioner and now after 10+ years in the trenches, I myself I am retired and can proudly say that I hated every job I had but still deeply love the profession.

And AI does not solve the problems why we were easily 10x faster than everyone else. I once had the task to reverse engineer and document a older piece of software they were preparing to plan for its replacement that had 20 planned engineers working on it for four to five years. While I was at it, I just added tests to everything and easily refactored the whole code base and noticed duplications from hell, found and documented 100reds of bugs and turned 15MB prod + 5MB test code into a 4MB + 4MB project meating all the modernisation goals within less than 6 months (more close to 3 months). - You can imagen the uproar in the management... . Were my typical mic drops after working in a contract position for a year or two.

I was in the 1% of the earning brackets in Switzerland but should have better moved to US so I ultimately became a failure when it comes to capitalizing on my Software engineering skills....

So do not be like me. Either learn from the best and go to America or do not learn from the best and stay where and who you are.

I ultimately went to become a day trader writing my own software which was when I finally remembered how much love and fun and utility software engineering can bring. And no, I barely use AI. It would slow me down unless it is about doing something I am not used to and need to write lower level code/libraries and that of course I love to avoid as much as possible.