Chapter 2 of 7 · 6 checks · 4 min
Learn the codebase and ship a first small change
How to build a mental map of the system and get a small, real change reviewed and merged in your first weeks.
Draw a rough map of the main services, data stores and how a request flowsMust
Why it matters and how to check
You do not need to read every file. Start with the shape: what services or modules exist, which database and queues they use, and how a typical request travels from the user to storage and back. Read the architecture docs if they exist and ask a teammate to walk you through the system for thirty minutes.
Sketch it on paper or in your notes, then ask someone to correct it. You are done when you can explain in two minutes where the code for a given feature probably lives.
Do
- Ask for a walkthrough and record your own notes
- Have a teammate check your diagram
Avoid
- Reading the codebase file by file from the top
Trace one real feature end to end with a debugger or logsShould
Why it matters and how to check
Pick a feature you used as a customer and follow it through the code. Set a breakpoint or add temporary logging, trigger the feature locally, and step through the handler, business logic and data access.
This teaches you the conventions (folder layout, naming, error handling, tests) faster than reading at random. You are done when you can point to the file where the feature starts, where its data is stored and where its tests live.
Do
- Read the tests for the feature you trace
- Note conventions you will copy in your own code
Avoid
- Leaving temporary logging in a commit
Ask for a small, well-defined starter task in your first week or twoMust
Why it matters and how to check
Ask your manager or buddy for a small task with a clear finish line: a bug fix, a small UI change, a missing test, a docs fix. Many teams label these as good first issues. The point is to learn the full path from ticket to production, not to impress anyone with size.
Before you start, confirm what done means: which behaviour changes, how it is tested and who will review. You are done choosing when you can describe the task and its acceptance check in one or two sentences.
Do
- Confirm acceptance criteria before writing code
Avoid
- Taking on a large feature as your first task
Keep your first pull request small and about one thingMust
Why it matters and how to check
Google's engineering practices say small changes are reviewed more quickly and more thoroughly, are less likely to introduce bugs and are easier to roll back. The right size is one self-contained change that does one thing and includes its tests.
For a first change, that might be a few dozen lines. If your change grows, split it. You are done when a reviewer could understand the whole pull request in one sitting, and it includes tests or a note on how you verified it.
Do
- Include tests with the change
- Split refactors from behaviour changes
Avoid
- Mixing formatting changes into a functional fix
Write a pull request description that says what changed and whyShould
Why it matters and how to check
A pull request description becomes part of the project's history. Google's guidance is that it should say what is being changed and why, with any context a reader would need, because future developers will search for it.
Start with a short summary line, then a paragraph on the reason and anything you decided that is not obvious from the code. Add how you tested it. You are done when someone who has never seen the ticket can understand the change from the description alone.
Do
- Link the ticket
- Explain how you tested it
Avoid
- Descriptions like "fix bug" or "updates"
Respond to every review comment and treat it as teachingShould
Why it matters and how to check
Review comments on your first changes are how you learn the team's standards. Reply to each comment, either by making the change or by explaining your reasoning politely and asking which option they prefer.
Write down patterns that come up more than once, such as naming or error handling conventions, and apply them next time without being asked. You are done when every comment is resolved and you have a short list of conventions you learned from the review.
Do
- Thank reviewers and ask follow-up questions
- Re-request review after pushing changes
Avoid
- Taking review comments personally
- Silently ignoring comments you disagree with