Getting Started With A Large Project

Screenshot of Rails repository — 10:10 GMT, 25th Jan 2019

Every software developer will likely come to a point where they have to contribute to a large project, whether it be a gigantic codebase with numerous commits and directories or an environment with different applications in a service-oriented architecture.

As an experienced developer, you’d be expected to get cracking real quick (or get ramped up quickly), but the interesting truth is that becoming a legend on a large codebase isn’t usually a walk in the park. Definitely gets better with more experience.

I’ve been lucky to start up some projects, as well as join some others that are quite large(over 25k commits). Of course, I actively follow the Rails repo(currently over 70k commits). In my experience, the following would make life easier when you’re getting started with a large project.

  • Understand the business: This cannot be overemphasized. For you to actively contribute to any business as a software developer, you need to understand the business as best as you can. Okay, it’s a very complex business that seems crazy to understand at a go, you should at least understand how your team impacts the business. You’re first an employee(or founder 😛) before you’re given access to the company’s codebase.
  • Interact with the production app: As intuitive as this sounds, many people never take time to interact with their team’s production application until they’re about to get their code deployed. You should, it gives more understanding of the use cases and edge cases of the application. However, if you feel like trying out something extreme that might break the app, you’d better be trying that in the staging/dev/review environment.
  • Read the documentation: Usually, the project should have a comprehensive readme or wiki or doc somewhere. While a decent team would let you know where you can find this during onboarding, it’s your responsibility to actually read it and pay attention to the information you find there. You might not need some of that info in your early days but they were put there for a reason.
  • Read the commit messages: If the team is one that cares about the next developer you should be able to see commit messages that actually inform you of what code additions do. This isn’t to say that you should read all commit messages but if you’re about to work on a file you could take a few minutes to check the history of that file.
  • Participate in code reviews: This helps both new and existing team members to know what’s going on, as well as learn more about the team coding styles, best practices and preferences. If you’re not feeling confident enough to make comments, you should feel free to at least take a look. I’ve reviewed PRs where all I could do was review the syntax and logic. I didn’t have enough knowledge of the business case for the PR. If I felt it was good, I’d go ahead to add a comment like: “Looks good to me. Although, I’m not very familiar with what this PR is doing”. Asides from the obvious fact that I now have an idea of what the PR is about, it also informs other team members to take time to review the PR.
  • Tests: Go through the tests, especially for files that you’ll be working on. It informs you of the cases that the team currently cares about and the edge cases they already considered. It also sometimes helps you to see how your objects and entities should be wired up (factories) and how they interact. You should also add/update tests for your added functionality, to ensure that you didn’t break anything or at least fix whatever you broke before launching. You most likely wouldn’t get past CI anyways 😅

Tip: Unless you’re really sure, never run all specs locally. They could take long minutes or hours. You should only run specs that relate to your work locally. Running the whole test suite is part of the responsibilities of your CI.

Oh, some projects have no tests and that’s not funny at all 💀

  • Seeds and Annotations: If you’re working with Rails, your project most likely has some seeds, that’s a good place to see how you can quickly create objects and their associations. If your team also uses model annotations, you should be able to see all active fields, constraints, defaults, foreign keys and indexes on the model files.
  • Pair and Ask Questions: Pairing with someone who’s more familiar with the codebase obviously makes life a lot easier. Feel free to ask questions too!
    I know there’s a bit of concern about asking questions for some folks, that would be a discussion for another day but yes, ask questions! Usually saves you a lot of time.
  • Search: You should always be quick to do a global search for identifiers(or files) in your editor. I’ve seen many people trying to look for where something was defined for minutes when a global search would do that in seconds.
  • Start with the smallest part: Whether you’re creating an object, writing spec, trying to walk through some logic or debug, start from the smallest part and understand it thoroughly.

These are a few of the things I’ve learned while working on teams with large codebases. Some of them I mastered quite easily, some I had to learn over time. Thoughts? Feel free to drop ‘em in the comments. Cheers!