8 ms·

How to join a team and learn a codebase (2020)

252 points by minicaionut 6y ago

cjfd 6y ago
All of this is true. To me this article mostly reads like 'water is wet'. What one often sees, though, is that younger developers often have the idea that they need to read through portions of the code as a step of getting into it. I am not really sure that it is a helpful step for all but the smallest code bases. It is often more helpful to start with a user story and then try to find out what portions of the code apply to that.
- swyx 6y ago
  it is true but as we all know checklists can help to make sure stuff isn't missed, even for very experienced people, and it is an unmitigatedly good thing for newer developers. i gave a go at making a cheatsheet of the steps: https://twitter.com/Coding_Career/status/1350445944395821056?s=20 https://twitter.com/Coding_Career/status/1350445944395821056... think it's a good guide to follow even if I instinctively do most of it already.
mettamage 6y ago
> The rule of thumb I use is to understand something just enough to express what it does without necessarily knowing exactly how it does that. This process is called "chunking," and it relies on the fact that once you have a basic understanding of a unit of code, "you don't need to remember all the little underlying details" (Oakley). Isn't this how a lot of non-math majors learn math at uni? You learn how to use it, but you don't learn the proofs behind it? When I dove into a first codebase, I took the above said approach because that's how I learned (most) math. A younger me would've find the Tools section valuable.
- Ace17 6y ago
  > You learn how to use it, but you don't learn the proofs behind it? Which makes sense, at least firstly, considering that understanding a proof is a lot easier when its conclusion is already familiar.
- Ma8ee 6y ago
  Oakley emphasises that understanding is an important part of chunking. Chunking is not the same as root learning without understanding. More that when you familiar enough with a concept you don’t have to think of all the details of it, but can treat it as a unit.
keithalewis 6y ago
I think I found the pony: do lots of little experiments to test your understanding of the code. The value of software is not in the bytes of the library/executable or even the source code. It is in having people working for your company who have a mental model of it in their head.
devdiary 6y ago
3 things that helped me become productive on new codebase faster 1. Start with a goal to fix a tiny issue. It will help you not go too deep, too early and yet give you an overview of the codebase. 2. Document the steps to setup dev environment in your own words and highlight the issues that you run into 3. Take time to learn the new Library or the tooling you encounter. Learn with the goal of familiarise yourself with the keywords/concepts of that library or the tools. It's okay even if you don't understand exactly how they work. When you really need to understand to solve a problem or a piece of code, you can use the keywords to quickly go to exact documentation references to learn more. A thumb of rule for me is to not invest more than a day to learn these new concept continuously(I can always come back to it if I see the need for that)
- gonzo41 6y ago
  2. Document the steps to setup dev environment in your own words and highlight the issues that you run into This is the most significant thing for me getting up to speed on a new or old project. I absolutely hate reading some whacky custom dependency, jboss, hell like project setups. They just kill morale. And I feel really bad when I see new starters wade into the tall grass on this stuff. I can almost see the moment they go to lunch and start thinking about quitting tech. My personal reaction to being given really bad 'quick start' doco so many times, is to try and leave every project I work on in a state where "mvn clean install" will do everything needed to get things running. You may join a team, but your team is also getting a new member. They should be working HARD to make you productive asap, and crazy dev setup is like a code smell.
  - berkes 6y ago
    I recently joined a new team and codebase. There was no 'getting started', no docs. I was left on my own. So I muddled through. And documented everything in Makefiles. Not readme, but working code. Now `make clean` `make install` etc, all run, deploy, install, clean etc the project. A great way to learn. But unfortunately worthless to others in the team, as they all were entrenched in their own ways and setups. I just added a sixth' way of 'working with the codebase'. I'm no to sure if it is the team, me, or Make, but I certainly won't spend such time a next new codebase arrives. (I do add makefiles on each of my private and opensource projects though, and will keep doing that)
smhmd 6y ago
The text on this blog needs more line height. I find myself tracing lines in order to read.
losthobbies 6y ago
Look at some low hanging fruit in the bug tracking system. See if there is a knowledge base - if there isn’t perhaps create one as you learn and ask others if you have the right idea. Could be useful for the next newbie in the door.
havkom 6y ago
I would recommend that when someone is new in a large project with an older code base, to pay attention and learn from others. A mistake I often see is too many “suggestions for improvement” too early. This behavior, when excessive as it often is, is perceived to be invalidating tough choices that were made before your time and chances are that the people who made the choices had good reasons for it and are more experienced than you are. Learn from your seniors - it may be hard when you’ve just read about this new “paradigm X which solves all problems” and you believe you are smarter than others - but please try.
- dan-robertson 6y ago
  This is a pretty one-sided take. I think it’s quite possible to lose perspective when working on a large codebase. It’s also possible to have small bits of technical debt accumulate without anyone feeling the total weight of it all. Old code can use whatever fad was most popular when it was written or it can carry the cruft of old dependencies or api changes. Just because something is old it doesn’t mean that it’s good
  - esc_colon_q 6y ago
    Being retarded enough to shit all over a codebase that you just met means you are a garbage employee who should never have been hired because you're a fucking boat-shaker. So go dickchoke yourself if you think this is reasonable, I have fired people for less than arrogant shit like this. Btw this is a lightning rod post, anyone who sees this please downvote and report!
  - williamdclt 6y ago
    Of course. But as a newcomer, you cannot know which one it is, and as the OP said this behaviour has a lot of chances to be perceived as invalidating. I've been on both sides of this situation, and in both cases I felt that it was almost disrespectful, it's sending the message that you don't think the team is competent enough to have considered them and carefully picked trade-offs. When I was on the receiving side (there was a newcomer to the team doing a lot of "suggestions for improvement"), I made a lot of effort to explain the context that led to a different decision, but it was very draining and rarely the good time for it (it distracts from the conversation), it was really hurting collaboration. Eventually we had a one-to-one in which I explained exactly that, and we found that it would be much better to raise these as "can you tell me why is this one like this" (rather than "improvement suggestion" that can be invalidating), and do it in one-to-one so that it's not distracting. Collaboration was much better after that For sure, it's great to have a new pair of eyes and you certainly don't want to tell somebody to keep their challenges and suggestion for improvement for themselves. But it doesn't mean that there's no good way or bad way to do it
oscare 6y ago
This is pretty good advice and I'm glad I recently did some of the steps at a new company. On the setup step I found it very helpful that my team has used scripts to rule them all, so setup was a breeze! I didn't know about that before. Short explanation: https://github.blog/2015-06-30-scripts-to-rule-them-all https://github.blog/2015-06-30-scripts-to-rule-them-all
ravirajx7 6y ago
For someone who is new in the team I would recommend : 1. Try to see what existing functionalities are there and how exactly the code is being executed line by line by putting debug points on the codebase. 2. Try to change the local codebase and see how the changes are affecting the application. 3. Whenever stuck - try your best to find out the errors and search for the solution for the errors present on the console. If facing more difficulty, better take help from seniors. 4. Think of the simplest approach you can use to develop a piece or make a change without affecting much of the codebase. 5. See other projects which uses same technology but with small codebases having same kind of implementation and try to learn the best practices followed also do visit documentation regularly because sometimes all you need is already explained in the simplest way.
nisa 6y ago
What helped me in a rather huge Java/Spring codebase with little documentation and little knowledge was running the code locally and using async-profiler to generate flamegraphs for requests to our rest-endpoints - then setting breakpoints in the ide and spending a few hours just following the requests to the code. It's not a good idea to rely on this for a complete understanding but I've remember attempting to read the code class by class before and was unable to get a mental model of it - after doing the flamegraph/stepping in the debugger dance a few days I've started to feel right at home - it also helped me quite a lot to pinpoint further issues.
shakezula 6y ago
I’ve always said the easiest way to learn a code base is to write tests for it. There’s always a flaky test someone just doesn’t want to fix, or a feature that doesn’t have any tests, or a couple components that don’t have an integration test, etc...
swyx 6y ago
i really liked this post and made it into a cheatsheet guide: https://twitter.com/Coding_Career/status/1350445944395821056?s=20 https://twitter.com/Coding_Career/status/1350445944395821056... thanks to OP for sharing it, its not the kind of thing that gets written down enough but funny enough it is really important to join a team well and nobody teaches how to do it.
danielovichdk 6y ago
I you really want to understand something, you have to change it. Or at least try hard.
- nullsense 6y ago
  This seems to be the best method by far. Though not terribly scalable. I think next place I go I will leverage this to greater effect early on.
chuckcode 6y ago
Go and talk with the people who wrote it. Often times there are a just a handful of people that wrote a lot of the core functionality, they often aren't the most social. Talk to them when you are in the planning phase of implementing something. Lots of great advice here that I agree with. IMHO though I see a lot of engineers miss on the team and social aspects of coding. Just as important as your tech stack is your team. Have an idea for improving something? That's great, but remember to listen first and learn to love what is great about the way it is. For you it could be X% better for the original authors it is a miracle that they made it work at all and it is important enough to need a bigger team.
- kostarelo 6y ago
  That, try to understand all the things that are not documented. Sure some projects may have written extensive documentation and all the options they considered and why the did what they did, but most of the decisions usually are not documented. Try to get into the mindset of those people and get into the conversation.
felixarba 6y ago
Interesting reading the comments how everyone has their own best way of joining a new team. For me, the best way to join a codebase without a doubt is to actually just use the product first. What good is looking at the code if you have no idea what the product is even supposed to do? This doesn't have to be in-depth knowledge, but just go through the setup of your product, do a few happy path use cases, feel what it's like to actually use the thing you're about to develop.
jariel 6y ago
It's >50% communication. - Setup docs have to be clean and well maintained, hopefully scripted. - Architectural overview has to be clear. - Other devs must make time for new devs, and that has to be communicated.
mcdoker18 6y ago
I wonder why no one has not mentioned tests. For me, the tests are more valuable for system or service understanding than, for example, documentation. But the best scenario when you combine tests and documentation. I have joined the new team recently. They have a lot of e2e BDD tests implemented using the Cucumber framework. It helps me to get a complete view of the system in the shortest possible time.
- stack_underflow 6y ago
  Somewhat related; I've always been very curious why a lot of developers I've worked with seem to think testing isn't worth the effort, and I've been keeping a mental checklist of all the reasons/excuses I hear so that I can reflect on them as well against my own experiences - sort of a way to challenge myself and ensure I'm not just cargo-culting methodologies. Recently I decided to go through `Growing Object-Oriented Software - Freeman, Pryce` (and actually finish working through it this time) with the goal of understanding what "proper TDD" is supposed to look like. Something interesting I noticed is almost all the complaints I've seen as reasons against TDD/certain testing methods all seem to be examples the authors use as how not to use TDD/testing. It seems to me that a lot of developers have just learned _of_ these techniques by name, and haven't really put a lot of time/effort into practicing their application and instead just seem to write them off on face value or by the literal interpretation of their names. One example, a lot of people I speak with seem to think TDD is very literal "write a _unit-test_* for everything before you write the implementation OR ELSE...", but of course there's a lot more nuance than that depending on the situation. The book actually puts a huge emphasis on having your initial test(s) be end-to-end tests that slice through the system as a whole, with the idea being to create nested feedback loops of varying granularity/abstraction to allow you to iterate without fear. This was something I never heard emphasized at all when I started learning about TDD, or hell even in a paid course my employer put us through by a "TDD expert". I should also clarify, I only consider these claims from developers that have a proven track record of working on large/complex systems since, well, those who don't probably haven't cultivated their ideal workflows/approaches yet (or just haven't been given the opportunity to showcase them, as is common in large companies). * I emphasize unit-test because a lot of code bases I've worked in rarely have anything other than just unit-tests...
xyzelement 6y ago
Things missing from the list: - get a demo of the system. Not from a developer but from a user/sales. - Understand the team objectives and goals on the high level. - Ask your team lead what small project you can do to get your feet wet in the system without an overwhelm. - get that first thing all the way out to prod so you learn what that's really like and what it takes.

252 points by minicaionut 6y ago

cjfd 6y ago

All of this is true. To me this article mostly reads like 'water is wet'. What one often sees, though, is that younger developers often have the idea that they need to read through portions of the code as a step of getting into it. I am not really sure that it is a helpful step for all but the smallest code bases. It is often more helpful to start with a user story and then try to find out what portions of the code apply to that.

swyx 6y ago
it is true but as we all know checklists can help to make sure stuff isn't missed, even for very experienced people, and it is an unmitigatedly good thing for newer developers. i gave a go at making a cheatsheet of the steps: https://twitter.com/Coding_Career/status/1350445944395821056?s=20 https://twitter.com/Coding_Career/status/1350445944395821056... think it's a good guide to follow even if I instinctively do most of it already.

mettamage 6y ago

> The rule of thumb I use is to understand something just enough to express what it does without necessarily knowing exactly how it does that. This process is called "chunking," and it relies on the fact that once you have a basic understanding of a unit of code, "you don't need to remember all the little underlying details" (Oakley). Isn't this how a lot of non-math majors learn math at uni? You learn how to use it, but you don't learn the proofs behind it? When I dove into a first codebase, I took the above said approach because that's how I learned (most) math. A younger me would've find the Tools section valuable.

Ace17 6y ago
> You learn how to use it, but you don't learn the proofs behind it? Which makes sense, at least firstly, considering that understanding a proof is a lot easier when its conclusion is already familiar.
Ma8ee 6y ago
Oakley emphasises that understanding is an important part of chunking. Chunking is not the same as root learning without understanding. More that when you familiar enough with a concept you don’t have to think of all the details of it, but can treat it as a unit.

keithalewis 6y ago

I think I found the pony: do lots of little experiments to test your understanding of the code. The value of software is not in the bytes of the library/executable or even the source code. It is in having people working for your company who have a mental model of it in their head.

devdiary 6y ago

3 things that helped me become productive on new codebase faster 1. Start with a goal to fix a tiny issue. It will help you not go too deep, too early and yet give you an overview of the codebase. 2. Document the steps to setup dev environment in your own words and highlight the issues that you run into 3. Take time to learn the new Library or the tooling you encounter. Learn with the goal of familiarise yourself with the keywords/concepts of that library or the tools. It's okay even if you don't understand exactly how they work. When you really need to understand to solve a problem or a piece of code, you can use the keywords to quickly go to exact documentation references to learn more. A thumb of rule for me is to not invest more than a day to learn these new concept continuously(I can always come back to it if I see the need for that)

gonzo41 6y ago
2. Document the steps to setup dev environment in your own words and highlight the issues that you run into This is the most significant thing for me getting up to speed on a new or old project. I absolutely hate reading some whacky custom dependency, jboss, hell like project setups. They just kill morale. And I feel really bad when I see new starters wade into the tall grass on this stuff. I can almost see the moment they go to lunch and start thinking about quitting tech. My personal reaction to being given really bad 'quick start' doco so many times, is to try and leave every project I work on in a state where "mvn clean install" will do everything needed to get things running. You may join a team, but your team is also getting a new member. They should be working HARD to make you productive asap, and crazy dev setup is like a code smell.
- berkes 6y ago
  I recently joined a new team and codebase. There was no 'getting started', no docs. I was left on my own. So I muddled through. And documented everything in Makefiles. Not readme, but working code. Now `make clean` `make install` etc, all run, deploy, install, clean etc the project. A great way to learn. But unfortunately worthless to others in the team, as they all were entrenched in their own ways and setups. I just added a sixth' way of 'working with the codebase'. I'm no to sure if it is the team, me, or Make, but I certainly won't spend such time a next new codebase arrives. (I do add makefiles on each of my private and opensource projects though, and will keep doing that)

smhmd 6y ago

The text on this blog needs more line height. I find myself tracing lines in order to read.

losthobbies 6y ago

Look at some low hanging fruit in the bug tracking system. See if there is a knowledge base - if there isn’t perhaps create one as you learn and ask others if you have the right idea. Could be useful for the next newbie in the door.

havkom 6y ago

I would recommend that when someone is new in a large project with an older code base, to pay attention and learn from others. A mistake I often see is too many “suggestions for improvement” too early. This behavior, when excessive as it often is, is perceived to be invalidating tough choices that were made before your time and chances are that the people who made the choices had good reasons for it and are more experienced than you are. Learn from your seniors - it may be hard when you’ve just read about this new “paradigm X which solves all problems” and you believe you are smarter than others - but please try.

dan-robertson 6y ago
This is a pretty one-sided take. I think it’s quite possible to lose perspective when working on a large codebase. It’s also possible to have small bits of technical debt accumulate without anyone feeling the total weight of it all. Old code can use whatever fad was most popular when it was written or it can carry the cruft of old dependencies or api changes. Just because something is old it doesn’t mean that it’s good
- esc_colon_q 6y ago
  Being retarded enough to shit all over a codebase that you just met means you are a garbage employee who should never have been hired because you're a fucking boat-shaker. So go dickchoke yourself if you think this is reasonable, I have fired people for less than arrogant shit like this. Btw this is a lightning rod post, anyone who sees this please downvote and report!
- williamdclt 6y ago
  Of course. But as a newcomer, you cannot know which one it is, and as the OP said this behaviour has a lot of chances to be perceived as invalidating. I've been on both sides of this situation, and in both cases I felt that it was almost disrespectful, it's sending the message that you don't think the team is competent enough to have considered them and carefully picked trade-offs. When I was on the receiving side (there was a newcomer to the team doing a lot of "suggestions for improvement"), I made a lot of effort to explain the context that led to a different decision, but it was very draining and rarely the good time for it (it distracts from the conversation), it was really hurting collaboration. Eventually we had a one-to-one in which I explained exactly that, and we found that it would be much better to raise these as "can you tell me why is this one like this" (rather than "improvement suggestion" that can be invalidating), and do it in one-to-one so that it's not distracting. Collaboration was much better after that For sure, it's great to have a new pair of eyes and you certainly don't want to tell somebody to keep their challenges and suggestion for improvement for themselves. But it doesn't mean that there's no good way or bad way to do it

oscare 6y ago

This is pretty good advice and I'm glad I recently did some of the steps at a new company. On the setup step I found it very helpful that my team has used scripts to rule them all, so setup was a breeze! I didn't know about that before. Short explanation: https://github.blog/2015-06-30-scripts-to-rule-them-all https://github.blog/2015-06-30-scripts-to-rule-them-all

ravirajx7 6y ago

For someone who is new in the team I would recommend : 1. Try to see what existing functionalities are there and how exactly the code is being executed line by line by putting debug points on the codebase. 2. Try to change the local codebase and see how the changes are affecting the application. 3. Whenever stuck - try your best to find out the errors and search for the solution for the errors present on the console. If facing more difficulty, better take help from seniors. 4. Think of the simplest approach you can use to develop a piece or make a change without affecting much of the codebase. 5. See other projects which uses same technology but with small codebases having same kind of implementation and try to learn the best practices followed also do visit documentation regularly because sometimes all you need is already explained in the simplest way.

nisa 6y ago

What helped me in a rather huge Java/Spring codebase with little documentation and little knowledge was running the code locally and using async-profiler to generate flamegraphs for requests to our rest-endpoints - then setting breakpoints in the ide and spending a few hours just following the requests to the code. It's not a good idea to rely on this for a complete understanding but I've remember attempting to read the code class by class before and was unable to get a mental model of it - after doing the flamegraph/stepping in the debugger dance a few days I've started to feel right at home - it also helped me quite a lot to pinpoint further issues.

shakezula 6y ago

I’ve always said the easiest way to learn a code base is to write tests for it. There’s always a flaky test someone just doesn’t want to fix, or a feature that doesn’t have any tests, or a couple components that don’t have an integration test, etc...

swyx 6y ago

i really liked this post and made it into a cheatsheet guide: https://twitter.com/Coding_Career/status/1350445944395821056?s=20 https://twitter.com/Coding_Career/status/1350445944395821056... thanks to OP for sharing it, its not the kind of thing that gets written down enough but funny enough it is really important to join a team well and nobody teaches how to do it.

danielovichdk 6y ago

I you really want to understand something, you have to change it. Or at least try hard.

nullsense 6y ago
This seems to be the best method by far. Though not terribly scalable. I think next place I go I will leverage this to greater effect early on.

chuckcode 6y ago

Go and talk with the people who wrote it. Often times there are a just a handful of people that wrote a lot of the core functionality, they often aren't the most social. Talk to them when you are in the planning phase of implementing something. Lots of great advice here that I agree with. IMHO though I see a lot of engineers miss on the team and social aspects of coding. Just as important as your tech stack is your team. Have an idea for improving something? That's great, but remember to listen first and learn to love what is great about the way it is. For you it could be X% better for the original authors it is a miracle that they made it work at all and it is important enough to need a bigger team.

kostarelo 6y ago
That, try to understand all the things that are not documented. Sure some projects may have written extensive documentation and all the options they considered and why the did what they did, but most of the decisions usually are not documented. Try to get into the mindset of those people and get into the conversation.

felixarba 6y ago

Interesting reading the comments how everyone has their own best way of joining a new team. For me, the best way to join a codebase without a doubt is to actually just use the product first. What good is looking at the code if you have no idea what the product is even supposed to do? This doesn't have to be in-depth knowledge, but just go through the setup of your product, do a few happy path use cases, feel what it's like to actually use the thing you're about to develop.

jariel 6y ago

It's >50% communication. - Setup docs have to be clean and well maintained, hopefully scripted. - Architectural overview has to be clear. - Other devs must make time for new devs, and that has to be communicated.

mcdoker18 6y ago

I wonder why no one has not mentioned tests. For me, the tests are more valuable for system or service understanding than, for example, documentation. But the best scenario when you combine tests and documentation. I have joined the new team recently. They have a lot of e2e BDD tests implemented using the Cucumber framework. It helps me to get a complete view of the system in the shortest possible time.

stack_underflow 6y ago
Somewhat related; I've always been very curious why a lot of developers I've worked with seem to think testing isn't worth the effort, and I've been keeping a mental checklist of all the reasons/excuses I hear so that I can reflect on them as well against my own experiences - sort of a way to challenge myself and ensure I'm not just cargo-culting methodologies. Recently I decided to go through `Growing Object-Oriented Software - Freeman, Pryce` (and actually finish working through it this time) with the goal of understanding what "proper TDD" is supposed to look like. Something interesting I noticed is almost all the complaints I've seen as reasons against TDD/certain testing methods all seem to be examples the authors use as how not to use TDD/testing. It seems to me that a lot of developers have just learned _of_ these techniques by name, and haven't really put a lot of time/effort into practicing their application and instead just seem to write them off on face value or by the literal interpretation of their names. One example, a lot of people I speak with seem to think TDD is very literal "write a _unit-test_* for everything before you write the implementation OR ELSE...", but of course there's a lot more nuance than that depending on the situation. The book actually puts a huge emphasis on having your initial test(s) be end-to-end tests that slice through the system as a whole, with the idea being to create nested feedback loops of varying granularity/abstraction to allow you to iterate without fear. This was something I never heard emphasized at all when I started learning about TDD, or hell even in a paid course my employer put us through by a "TDD expert". I should also clarify, I only consider these claims from developers that have a proven track record of working on large/complex systems since, well, those who don't probably haven't cultivated their ideal workflows/approaches yet (or just haven't been given the opportunity to showcase them, as is common in large companies). * I emphasize unit-test because a lot of code bases I've worked in rarely have anything other than just unit-tests...

xyzelement 6y ago

Things missing from the list: - get a demo of the system. Not from a developer but from a user/sales. - Understand the team objectives and goals on the high level. - Ask your team lead what small project you can do to get your feet wet in the system without an overwhelm. - get that first thing all the way out to prod so you learn what that's really like and what it takes.