How to familiarize yourself with a new app

Opening up a new project that you're unfamiliar with can be daunting. Where do you start? What does the stack look like? After working at Tighten for two years and routinely switching to different projects, I have developed a system to familiarize myself with an application quickly.

Step 1: What are we working with?

When reviewing a new app, I like to look at the composer.json and package.json to get a high-level overview of the app. If the Laravel version is 8 or 9, I would note that the structure will differ from a brand-new app and that I might want to upgrade. I also look at if Livewire or Inertia.js are installed; these will tell me where to expect frontend logic to live. In addition, it's helpful to keep an eye out for any package that is unfamiliar and look it up to learn more about it. By doing this step in the beginning I can have an idea of what the app might do, or features it implements when exploring in Step 3.

Step 2: Can we get up and running?

Reviewing the README.md is a crucial step before installing. Projects with more complicated setups (i.e. anything with Docker) often describe the steps needed to start. For example, Tighten's Ozzie project has an in-depth section on setting up a local installation.

In general, this process includes cloning the repository, copy the environment example file, install composer and npm packages, generate an app key, migrate the database, and seeding the database. The specific process and commands that I use for nine out of ten projects can be found below:

1. Clone the repo (git clone git@github.com:org/repo.git)
2. Install dependencies from within the repository's folder (composer install && npm install)
3. Copy the example .env file: cp .env.example .env
4. Run php artisan key:generate
5. Run php artisan migrate:fresh --seed

Before moving on to the next step, it is helpful to run the tests to get a general state of the app. If everything passes, I can assume everything is installed correctly. If tests fail and the project has continuous integration actions, I'll look at those to see how long they have been failing. This tells me how much the maintainers care about keeping their tests current. Sometimes, when tests fail, it lets me know I'm missing a key or dependency. For example, a project I was on used AWS heavily, and an S3 key to get the tests to pass.

Step 3: Follow the code

Next, I like clicking around the application and following my path in my code editor. I'll go to the root page, try to register, go to different pages, and play around. While doing that, I follow the path I take in my code editor. I'll look at the routes/web.php to find the route that matches the page I'm currently on, then follow it to the controller (or Livewire component). When the page is doing something interesting or different, I also open the view to look at that. While going through this process, I take notes of any questions I have and anything, interesting or unusual.

Step 4: Ask Questions

While making notes, I do my best to explore the code to answer any questions, but sometimes, the best thing to do is ask another person on the project to answer them. Any issues I have may be attributed to institutional intricacies I wouldn't be familiar with.

Asking questions can go a long way to help you understand the code and create goodwill with the other developers on the project. When asking questions, I do my best to frame them to indicate a desire to understand and wrap my head around the code. I do not want them to think that the code is wrong, or by extensions, they're bad for writing it.