DEV Community


Discussion on: What Makes an Effective Code Walk Through?

kaydacode profile image
Kim Arnett 

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.

simonhaisz profile image

@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.

goyo profile image
Grzegorz Ziemonski

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.

scrabill profile image
Shannon Crabill

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.

derekjhopper profile image
Derek Hopper

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.