How I Onboard Myself to a New Android Codebase

Every time I've joined a new team, I've inherited a codebase with tens of thousands of lines of code, years of history, and conventions that nobody wrote down. The temptation is to read everything. That doesn't work. Codebases are too big and too interconnected to understand by reading linearly.

Instead, I follow a system. It takes about two weeks and it gets me from "where is anything" to "I can ship a meaningful change" faster than any other approach I've tried.

Week 1: Map the Territory

Day 1-2: Build and Run

Before reading any code, I build the project and run it. I tap through every screen. I try to break things. I note what feels slow, what looks weird, what crashes.

This gives me a user-level mental model that no amount of code reading provides.

Day 3-4: Trace One Feature End-to-End

I pick one feature and trace it from UI to network and back. Not a simple one. Something substantial like "user opens the app, sees their feed, taps a post, and leaves a comment."

Entry point: MainActivity.onCreate()
  → NavGraph → FeedFragment
    → FeedViewModel.loadFeed()
      → FeedRepository.getFeed()
        → FeedApiService.fetchFeed() [Retrofit]
        → FeedDao.getCachedFeed() [Room]
      → Maps to FeedUiState
    → FeedAdapter renders items
      → PostViewHolder binds data
  → User taps post → navigates to PostDetailFragment
    → PostDetailViewModel.loadPost(id)
      → Same repository pattern

This one trace teaches me the project's architecture patterns, dependency injection setup, navigation approach, data layer conventions, and naming conventions. One feature tells me how every feature works.

Day 5: Read the Build Configuration

build.gradle files tell you more about a project than most documentation. I look at:

Min SDK and target SDK (what devices matter)
Dependencies (what libraries the team chose and why)
Build variants and flavors (how the app is configured for different environments)
Custom plugins or build scripts (where the team has automated things)

Week 2: Start Contributing

Day 6-7: Fix a Small Bug

I find a small, well-defined bug and fix it. Not to prove myself, but to learn the team's workflow. How do they branch? What's the PR process? What do code reviews look like? What CI checks run?

The fix itself is secondary. The process knowledge is the real goal.

Day 8-10: Ask the Right Questions

By now I have a list of things I don't understand. I prioritize them and ask teammates directly. Not "how does this work?" but specific questions:

"I see FeedRepository uses both Room and the API. What determines when we use cached data vs fresh data?"
"The UserSession class is referenced everywhere. Is there a reason it's a singleton instead of scoped to the activity?"
"I noticed the tests in feature-x use a different mocking approach than feature-y. Is there a preferred pattern?"

Specific questions get useful answers. Vague questions get vague answers.

What I Don't Do

I don't read documentation first. Internal docs are almost always outdated. The code is the source of truth.

I don't try to understand everything. I understand one vertical slice deeply, then expand outward as needed.

I don't refactor during onboarding. It's tempting to "improve" code you're learning. Resist. You don't have enough context yet to know what's intentional and what's accidental.

I don't stay quiet when I'm confused. Asking questions early is a sign of engagement, not incompetence. The engineers I respect most are the ones who ask the best questions.

The Mental Model That Helps Most

I think of a new codebase as a city I've never visited. I don't need to know every street to get around. I need to know the major landmarks (entry points), the main roads (data flow patterns), and the neighborhoods (feature modules). The back alleys can wait.

After two weeks, I can navigate confidently. After a month, I know the shortcuts. After three months, I know where the construction is happening and why. That's enough to be productive, and it's earned through doing, not reading.