Starting on a new codebase is one of the most disorienting experiences in software development. The code is unfamiliar, the domain is new, the team has years of context you do not have, and you are expected to contribute quickly. Most developers muddle through this by reading randomly until something clicks. There is a better way.
The instinct on day one is to open files and start reading. Resist it. The first 48 hours should be spent orienting — understanding the shape of the system, not the content of individual files.
Find the system diagram if one exists. Read the README. Look at the top-level folder structure. Find out what the system's main job is, what it talks to, and what talks to it. Draw a rough map on paper. This map will be wrong, but having a wrong map is better than having no map — it gives you something to correct as you learn.
The goal of the first 48 hours is not to understand the code. It is to be able to ask better questions.
Every codebase has a small number of files that explain more than the rest combined. These are the tour guide files: README, CHANGELOG, ADR (Architecture Decision Records), CONTRIBUTING, and any onboarding docs the team maintains.
ADRs are especially valuable. An Architecture Decision Record documents why a significant decision was made — why this database, why this library, why this pattern. Reading ADRs tells you what the team tried, what failed, and what constraints shaped the current design. Without ADRs, you will rediscover those constraints the hard way.
If no ADRs exist, the git log serves as a rough substitute. Long commit messages from early in the repository's history often contain the reasoning that ADRs would have captured.
The most effective onboarding technique is to trace a real bug or ticket from symptom to fix — not to read the codebase top to bottom. A bug gives you a thread: you start at the symptom, follow the execution path, and end with a change that is small enough to understand completely.
This technique works because it forces you to read code in context. Every file you open, you open for a reason. Every function you trace, you trace because it is part of the answer. This is fundamentally different from exploratory reading, where you open files without a destination and retain almost nothing.
Pick a bug that was recently fixed — not an open one. Read the fix first, then try to understand why it works. This gives you the answer before you see the question, which makes the question much easier to understand.
New developers often ask colleagues questions that a search or a README could answer: "where is the config file?", "how do I run the tests?". This is a waste of everyone's time and erodes the trust that makes future questions welcome.
The questions worth asking colleagues are the ones that require context only they have: "why does this service own this data instead of that service?", "what was the reasoning behind this design?", "is this pattern intentional or is it debt we are planning to address?"
The distinction is between questions about facts (find them yourself) and questions about decisions (ask the people who made them). Preparing this distinction before your first week saves you from being the developer who asks too much of the wrong kind.
Every codebase is written in two languages: the programming language and the domain language. The domain language is the vocabulary of the business — the words the domain experts use that have specific, precise meanings different from their everyday usage.
In a payments system, "settlement" means something specific. In a healthcare system, "encounter" means something specific. In logistics, "manifest" means something specific. Misunderstanding domain vocabulary causes bugs that look like logic errors but are actually semantic errors — the code does what you wrote, not what the domain requires.
Build a glossary as you onboard. When you see a term you do not recognize, look it up in the domain, not just in the code. Ask a domain expert, not just a developer. The glossary will save you hours of confused reading.
Onboarding has no clear end state, which makes it easy to feel permanently lost. A useful heuristic: track how long it takes you to answer a question about the system. In week one, every question requires asking someone or spending an hour reading. In week four, most questions can be answered by reading for ten minutes. In week eight, most questions can be answered from memory.
If week four looks like week one, that is a signal — not that you are slow, but that your reading strategy is not building retained understanding. Passive reading accumulates exposure without building knowledge. Active reading — explaining what you read, testing your understanding against the code's actual behavior, asking what would break this — builds the mental model that makes future reading faster.