Hi All!
First dev.to post, this is exciting!
Throughout my very brief software development career, I've been onboarded to various projects. Each one of these onboarding sessions had a code walkthrough of some sort. There were slide decks, handouts, and an endless sea of confluence pages. These methods (and various combinations), all have their pros and cons, but I can't help but think there must be a better way to go about this.
Question
What types of code walk through sessions have you found to be particularly effective and why?
Top comments (8)
Code walkthroughs are so dry and taxing - especially if you're seeing the system for the first time. I also believe it resonates with people in very different ways. For example: Some might receive the slides well.. but for me it just puts me to sleep.
I do enjoy a high level overview - how do the systems interact, how is the project laid out type things, and for me the easiest way to navigate into the deep end is pulling up my sleeves and get to work. Outside of corporate training, by my second day at Expedia I was writing & debugging code. I had co-workers as resources to ask if I needed clarification on something, and by day 3 I had my first PR up to the system. As overwhelming as it can seem - I truly feel diving in is the quickest and most interesting way to ramp up.
Completely agree. It's almost like a deep dive presentation has little to no value. However, it's weird how some sort of presentation seems necessary though. I'm not sure why that is. Maybe it seems like the considerate thing to do for someone new to the team.
Instead of one big tour of the code base, maybe it should be thought of as hundreds of little tours over time. That's when you really start to understand the grand scheme of it.
@tayloredwards ^ this.
The problem isn't that you've gone through bad code-walkthrough, so the best question isn't "how do you do good code-walkthroughs?". The reality is that code-walkthroughs are bad way to onboard someone to a new codebase, for all of the reasons that the other responders pointed out.
So the better question is "what are good ways to onboard someone to a new codebase?".
I won't reiterate the answers that the others provided, which are all good. Instead I want to go on a bit of a tangent about asking the wrong question and how you can learn from this to ask better questions for similar problems you will encounter in your career.
You encountered a bad solution to a problem and you knew it was bad. You wanted to improve it. That's great! This issue is, and we've all been there, you assumed the fundamental approach to the problem was sound and it just needed some changes.
Do you know what interaction that is similar that you will encounter throughout your career? When PM gives you "requirements". It is very common for developers to receive requirements in the form of a solution to a problem rather than the problem itself. Often the solution is the obvious, valid one for the problem However, it can be very difficult to separate those from the cases where they aren't when all you are dealing with are solutions so I think it's always worth the time to drill back to the actual problem.
Drilling back to the root problem a solution is trying to solve is an important skill you will continue to use throughout your career that doesn't just apply to validating requirements. Anytime your encounter an issue where something doesn't seem to work right, before you go and try to fix it you should figure out the problem it was trying to solve in the first place. I wish I had learned this lesson when I was at your stage of my career.
I agree that the format of the walkthrough (slides, shadow, etc) should be tailored to the individual or team. For me, slides or documentation is a handy reference, but either diving in head first or shadowing someone would be my preferred way to learn.
I work more on the front-end, but we tend to have people shadow with teammates on their first few days. They can take notes, sometimes there are handouts or wiki pages to read in their downtime, but mostly its to watch and ask questions.
This. I can confirm based on a few cases, both mine and other developers' that a high-level overview + something to do deep in the code is a great way to introduce a new dev to the project.
At my current and previous jobs, I was given a brief overview of what the whole application did and then a bit on naming conventions and how this particular team seperated the various layers, and then I was thrown in the deep end with my first issue in the ticket management system. It was something that had already been analysed by someone more experienced with the code base, and they told me that they expected me to harass them for help all day.
At my current job, we're all remote workers, so they made a special effort to all be together and available for that first week.
Obviously this works for a new hire who is already very experienced in the language and tools, skilled in the art of software archaeology. It wouldn't work so well for hiring someone less experienced. For that I prefer to do the same brief introduction but then spend the first week pair-programming.
I think an overly detailed code walkthrough or lots of reading may be a problematic approach. I favor a higher level overview so information will be retained. Beyond that, methods for helping others help themselves, such as how other developers typically work through an issue. I think the value of more senior people on the team is not their knowledge of the particular codebase (but it definitely helps) but more so how they got to be a senior member. What are their strategies for being effective? These are things that will likely translate across projects in some way.
Walkthroughs are boring. I've been on the giving end of a walkthrough and I bored myself while explaining the code :D Fortunately I only had to go through the high level because the other programmer was far more experienced in programming than I am, he just didn't know about the project.
A better way? The high level overview mabye while using the actual application so that a person know which part does what. Tests sometimes help the newcomer because they are mini examples of how the code should be used.