Ask HN: Onboarded and overwhelmed by new code base
I am doing a SWE internship and the company shared their codebase with me on git and I am very overwhelmed with all the moving parts. Ive never joined in to a project like this and am wondering the best approach to get familiar with things.
7 comments
A common trap is trying to learn all the parts and reading the docs. Docs for most codebases are out of date. We stopped doing docs - most engineers are better at reading code than the docs, and we design things in a way that when someone leaves or joins, things can be picked up without docs.
First, learn how the parts connect to one another.
You want to add a button. What is that button connected to? What runs underneath? Where does that change? Does it go through an API? Is the value tracked in a global variable?
What else is a value connected to? How is change displayed? Often changes in value are observed in modern code, but it can also be manually changed when a value is changed.
You don't want to learn parts because parts are easily replaced. Learn connections between those parts.
Some things appear invisible to those who have worked in similar systems. These don't show up in docs sometimes, which makes the learning curve steeper.
Next: learn purpose.
Why not purpose then connections? A system can be corrupted from its purpose. Things will eventually rewire to suit the purpose, but they don't function that way now.
Purposes can change too. When a code is written by a large contractor, the purpose is to make money. When that code is passed to the client, the purpose is to keep doing what it does and also to save money and time. When you see major refactors, it can be because of a change in purpose, but it's useful to understand how and why it's changing.
Sometimes there's no purpose - someone copied something they didn't understand.
Docs are good at denoting purposes too, so this is a good place to read them.
First, learn how the parts connect to one another.
You want to add a button. What is that button connected to? What runs underneath? Where does that change? Does it go through an API? Is the value tracked in a global variable?
What else is a value connected to? How is change displayed? Often changes in value are observed in modern code, but it can also be manually changed when a value is changed.
You don't want to learn parts because parts are easily replaced. Learn connections between those parts.
Some things appear invisible to those who have worked in similar systems. These don't show up in docs sometimes, which makes the learning curve steeper.
Next: learn purpose.
Why not purpose then connections? A system can be corrupted from its purpose. Things will eventually rewire to suit the purpose, but they don't function that way now.
Purposes can change too. When a code is written by a large contractor, the purpose is to make money. When that code is passed to the client, the purpose is to keep doing what it does and also to save money and time. When you see major refactors, it can be because of a change in purpose, but it's useful to understand how and why it's changing.
Sometimes there's no purpose - someone copied something they didn't understand.
Docs are good at denoting purposes too, so this is a good place to read them.
I've been there. You have to communicate with your manager and be honest about how much you can do how quickly. Start small, with one component in one programming language. Learn the language and the frameworks. Ideally you'll be allowed time to do so. After you're familiar with the technologies the code will be easier to understand. Make notes on the code. Read the docs and if they're missing info, find out and fill it in; that way you're learning and contributing. I like starting from the database models, data is usually the heart of an application. It's important not to feel like you have to rush. Learning big things takes time.
How to Learn a Code Base:
1. Read any documentation
2. Examine the front-end
3. Study the permanent data streams and persistent data
4. Learn the class / type system and map it out
5. Find the code's locations and see how the code is processed
6. Categorize the code by functionality and map it out
7. Study the back-end CRUD operations
8. Study the front-end CRUD operations
9. Study the permissions and security infrastructure
10. Study a well-defined data collection or functional area
Source: not me; I lost the original source document.
1. Read any documentation
2. Examine the front-end
3. Study the permanent data streams and persistent data
4. Learn the class / type system and map it out
5. Find the code's locations and see how the code is processed
6. Categorize the code by functionality and map it out
7. Study the back-end CRUD operations
8. Study the front-end CRUD operations
9. Study the permissions and security infrastructure
10. Study a well-defined data collection or functional area
Source: not me; I lost the original source document.
Most cases when a company shares the codebase it's to give you freedom to explore what you'll be working with while they decide what specifics tasks you'll be undertaking.
Get your dev space up and running and play around with stuff you read in available docs.
Get your dev space up and running and play around with stuff you read in available docs.
- See if you can pair with someone a few months or a year ahead of you. They'll be new enough to remember what it's like to be new, but experienced enough to give you advice. Seniors devs can sometimes be very busy, not approachable, and don't remember what it's like to be new
- Just read the entire codebase...I know that's not very popular, or efficient. If it's an enormous codebase, just take it folder-by-folder. Skim large files or things you don't understand. Eventually something will pop out as familiar and you'll notice some patterns. Ask questions about those patterns and see if your intuition is correct.
- Figure out what the output is supposed to be. Is it a web app? Get it running locally so you can view it in a browser. Something else? Run the test suite and see what the tests actually do. If it's an embedded project or something that runs on hardware, ask for an experienced dev to introduce you to the hardware and show you how to upload and run builds on it.
- Find the entry point for the application. Some sort of main() function, depending on the language. Surrounding it will be some clues as to what the high-level architecture is.
Hope that helps!
- Just read the entire codebase...I know that's not very popular, or efficient. If it's an enormous codebase, just take it folder-by-folder. Skim large files or things you don't understand. Eventually something will pop out as familiar and you'll notice some patterns. Ask questions about those patterns and see if your intuition is correct.
- Figure out what the output is supposed to be. Is it a web app? Get it running locally so you can view it in a browser. Something else? Run the test suite and see what the tests actually do. If it's an embedded project or something that runs on hardware, ask for an experienced dev to introduce you to the hardware and show you how to upload and run builds on it.
- Find the entry point for the application. Some sort of main() function, depending on the language. Surrounding it will be some clues as to what the high-level architecture is.
Hope that helps!
thank you so much!
Learn by doing.
Fix a couple of nontrivial bugs.
Implement a new feature.
Get comfortable with the fact that you'll be slower than others.
Fix a couple of nontrivial bugs.
Implement a new feature.
Get comfortable with the fact that you'll be slower than others.
Welcome to the real world of software engineering. It only gets worse.