I'm a self-taught programmer. Up until now I haven't had too much problems building things I have wanted to. Historically, given an issue, especially one I have caused I haven't had much of a problem figuring it out. This all changed about two months ago, when I was offered my first position at a company whom I became acquainted with after a pull request to a framework they use.

I relocated for the position and I really like the environment, it's a small team of about ten people, and from what I can tell they all seem to be incredibly talented. They gave me a pet project to do in which I had mostly full autonomy over. They stressed that they dont expect developers to become entirely productive and profitable until about the 3-6 month marks and that this project would help them understand where I'm at as a developer. It felt great and after a month I was put on one of their bigger projects on one of their most longstanding contracts.

After switching to this project I felt kind of overwhelmed, it is a LARGE codebase where changes are very visible to our clients clients, as it powers a number of sites. It is also a very complex codebase, while I attribute a lot of my hardship to my lack of experience it was originally a rescue project, syncs everything between two seperate frameworks and has a number of models that do thing I cannot given my experience understand, has no documentation, and a test coverage of 85%. I was originally tasked with making a few small changes, things like implementing honeybadger notifications on mail delivery failures, or rewriting minitest tests to rspec specs.

Then I was tasked with upgrading one of the frameworks that the project depends on. This has taken me an abnormally large amount of time, and I was retasked to something else until one of the senior developers comes back from holidays to act as a support system during the process. The task I was reassigned to turned out to be giving me an equally large amount of trouble.

I had a sit down with my employers and talked to them about this. They stated that it's normal given my experience and that I currently meet their expectations. However, this is the first time in my life I really could not do what I set out to in any amount of reasonable time. Is this a feeling that is shared among others, is it a normal occurrence?

What would be the expected amount of time to become acquainted wit a large codebase of say 50,000 lines? Are there any other practices that I may not know about that could help me become familiar with a codebase faster?

  • Hello! Sorry to hear you are having hardships - if it helps, I spent the first two years at my job wondering if I was doing OK. At any rate, could you get a bit more specific about the types of problems you're having? For example, what was the nature of the other task that isn't going so well? As a side note, one thing I have found particularly useful (if it doesn't already exist) is to map out all the classes and how they talk to each other. No UML, nothing fancy - whatever makes sense in your head. Takes a while, but quite helpful to see visually.
    – J Trana
    Commented Jan 5, 2014 at 6:12
  • Relevant: stackoverflow.com/questions/215076/…
    – Jim G.
    Commented Jan 5, 2014 at 8:55
  • 1
    Related: programmers.stackexchange.com/questions/201724/… Commented Jan 5, 2014 at 11:44

5 Answers 5


I have had good success to learn new code bases with the following approach. Strive to understand:

  1. Purpose: understand what the system or framework does, conceptually speaking
  2. Architecture: create a view on the overall architecture of the system or framework
  3. Components: learn how major parts (components) work together
  4. Code: now you are ready to take deep dives by debugging major flows through the code base, e.g. while fixing a bug

Here's the rationale for each of these steps, and how you could approach them. Note it may take you several iterations going from step 1 to 4. Take your time.


This may sound obvious, yet I find that even experienced developers sometimes lack a basic understanding of what the system's main purpose is. Strive to learn the business concepts *) free from technology first (i.e. ask questions like: "this system processes customer orders and issues invoices -- what is a customer, how do orders and invoices look like, what does it mean to issue an invoice? Who is using the system? What do they need to do with it?" etc.)

*) "business" meaning: from the customer's or user's point of view

Knowing the conceptual level without specifically looking at technology is a major plus in getting to understand its inner most workings -- code is merely a means to an end and without knowing the end all code is essentially meaningless, and so it will appear. If you don't have a conceptual understanding yet, ask someone to explain. If you think you do, explain it to someone more senior on the project. You will learn a lot either way.


Next, strive to understand the overall architecture. This is at a technology level, but without looking at the detail implementation. Examples of the architecture level are:

  • tiers - e.g. web tier, business tier, database tier, front-end, backend, ...
  • layers - e.g. user interface, business model, service interfaces, ORM,...
  • major components - e.g. order processor, invoice generator, customer manager, ...
  • infrastructure - e.g. network setup, servers, message queues,

Again, if you don't know any of this yet, ask someone to give you an overview (within at most 1-2 hours to avoid getting lost in details). You will benefit from documenting the results of such an introduction, start with simple diagrams first (maybe using Visio or similar tools), and over time develop the ability to use a more formal approach such as UML. The process of documenting may sound tedious and useless, yet it is uterly useful as it is not the result that counts but the thinking process that goes into drawing the diagrams.


Looking at the major components, understand how they work together to achieve the purpose of the system. Go back to the conceptual level and map the concepts and what users do to each of the components. Draw flow charts or sequence diagrams to see how data flows through the system. Again the main purpose of drawing is not the diagrams as such, but to force your brain to think it through.

This is also a good time to map components to code. Usually such components are made of several parts (e.g. several programs, classes, database scripts or whatever code artifacts your system uses). It is good enough to understand, for each component, where the respective code is located -- later on you can still dive into details.

A note of caution: it may be that your co-workers don't have a notion of "components" other than actual code artifacts -- that's not untypical if someone is deeply immersed with the code base. Try to ask questions such as "looking at the code base overall, are there areas such as programs/packages/classes that belong together? What is their purpose, as a group? Which of these need to work toegether to achieve X?"


Take one particular entry point into the system - e.g. a user interface, a web service, an API etc. and set up a debug session. Then step through the code, always paying attention to which component the currently executed code belongs to. In your mind, map this actual flow back to your earlier flow charts and maybe update them if you find missing gaps.

Instead of stepping through the code in a debug session you could also use a profiler. That is, a program that records the flow for you and displays a hierarchy of all subroutine calls.

Another alternative is to use a code analyzer / reverse engineering tool that is able to decern a hierarchy of dependencies. However in my experience these tools generate too much data to be useful for the novice, that's why I would prefer the debugging approach.

  • To "Purpose" I would add "terminology". Very important to know what a thing means because classes/methods usually use the same terms.
    – Sulthan
    Commented Jan 5, 2014 at 11:21
  • This is a good answer and the only additional info that I would add is a link to Michael Feathers's book, "Working Effectively with Legacy Code", a must-have when diving into the code of the legacy beast
    – user7433
    Commented Jan 6, 2014 at 16:34

You said you're a self-taught programmer and by this question I assume you don't have prior experience with such big projects.

Personally, I have less experience than you so do not take my words as gift of god. Honestly, I think it's perfectly normal to be overwhelmed from such big projects when you don't have prior experience. If they expressed already that you meet their expectations then you really shouldn't worry about it so much.

As you said there's no documentation, try to improve the documentation if they allow you to. That would make everyone a favour for sure.

TLDR; Give it time. Get used to it. Don't be afraid to ask questions and take it positively - in a year or two you'll laught at it wondering how the hell you couldn't underestand such simple code.


You say it yourself: I'm a self-taught programmer. Books and linear courses got you this far, but have reached their limit. Time to dispense with passive instruction. Get serious: get formal teaching.

Most people improve significantly when they engage a teacher: someone who can look at you subjectively and focus on your personal strengths and weaknesses. That might mean a course at a school, sitting next to a more experienced colleague who is happy to help you, or even a modern online course that provides subjective feedback.

  • 2
    University in my previous experience doesn't usually involve 1 on 1 learning, even during office hours. Even though returning to school is something I'd much like to do, for now I don't have the resources or the means to do so. I have other coworkers that sit beside me but that's about it.
    – Senjai
    Commented Jan 5, 2014 at 18:27
  • @JohnMee Not necessarily. I know people w/o prior big project experience making it farther. It just takes a lot of time to understand any big codebase. Commented Feb 11, 2021 at 14:14

How long for ~50kloc? Maybe 2-3 weeks. of course it will take longer if you're also learning the language, framework or tools. The key thing to realize is that you're meeting your employer's expectations. There's no need to stress out too much, as that will lead to mistakes.

What can you do? Experiment. Tinker. Fiddle.

Take the codebase and change something to see how it works - and see what it breaks. You said the codebase has good test coverage, so you should have good visibility into how your changes impact the code.

If you encounter something you don't know, do some research to learn about it, but then make a prototype. Take that new concept and toy with it in a safe environment where you don't feel the pressure of work or client demands.

The best way to learn something is to work with it.

  • I think one of my biggest issues is doing too much research, and then still not figuring out the issue. I think I should ask more often and sooner, hopefully not to the point of being annoying though.
    – Senjai
    Commented Jan 5, 2014 at 18:28

Studies have shown that people who go to sleep immediately after studying have twice the recall rates of those that have distractions between studying and sleep.

It's amazing really.

Read the stuff just before bed, and be sure to not allow any other distractions between your reading and bed time. Fill your brain full of facts until you can't hold any more, and then hit the sheets.

Using this technique I became certified in 4 languages one winter in a span of only a few months, (i.e. I was able to pass a certification test in these languages). In one of the languages I was able to hit top of my class because of almost near perfect test results. I don't think I ever could have done this without this learning technique.

I read this many years ago in a book on cognition, and it has served me well over the years.

Sad that more people aren't taught this at an early age.

  • 2
    Care to provide some references?
    – Telastyn
    Commented Jan 6, 2014 at 2:44
  • Sorry, I can't. It was in a book on cognition that I read ages ago. I was studying AI (artificial intelligence) at the time and trying to understand how the human brain worked. Commented Jan 6, 2014 at 2:58
  • 2
    Sounds a little pseudosciencey
    – Senjai
    Commented Jan 7, 2014 at 4:23

Not the answer you're looking for? Browse other questions tagged or ask your own question.