I have been tasked with teaching other teams a new codebase, but I keep running into an issue. Whenever I go to actually walk through the code with people, we don't get very far before the entire exercise devolves into a bikeshedding (members of an organisation giving disproportionate weight to trivial issues) exercise. Since they don't know the codebase, but think they need to help improve it, they focus on the things they can understand:

Why is that named that? (2 minutes to explain why it's named that, 10+ minutes debating a new name)

Why is that an abstract base class rather than an interface? (2 minutes to explain, 10+ minutes debating the relative merits of this decision)

...and so on. Now, don't get me wrong - good names and good, consistent design are important, but we never get to discussing what the code actually does or how the system is designed in any meaningful way. I've done some meeting refereeing to get people out of these tangents, but they're gone - distracted by what the code will/should be when their pet triviality is fixed, and they miss the bigger picture.

So we try again later (or with a different part of the codebase) and since people didn't get enough knowledge to overcome the bikeshedding effect, it repeats.

I've tried smaller groups, bigger groups, code, whiteboarding, visio diagrams, giant walls of text, letting them just argue it to death, cutting arguments short immediately... some help more than others, but nothing works. Hell, I even tried having other people from my team explain it because I thought it might be that I'm just bad at explaining things.

So how do you educate other programmers enough that they stop fixating on trivialities and can meaningfully contribute to the design?

  • 45
    I hate to say it, but it sounds to me like this phenomenon is illustrating more of a problem with the codebase than with the newcomers.
    – Nicole
    Commented Nov 21, 2013 at 2:27
  • 30
    Have you tried deferring questions to the end? "Hang on for a few more minutes and I can explain at the end" and then just pushing through the rest of the content. Perhaps some of these questions will answer themselves Commented Nov 21, 2013 at 2:36
  • 21
    @NickC, I believe that whether the code is good or not has nothing to do with how you get to understand it, how you manage to get a clear big picture of it. Wasting time on small details from the get-go without taking the time to get an initial big picture is bad and will never help in fixing that potential bad code. Commented Nov 21, 2013 at 15:31
  • 11
    What is the goal of teaching someone the codebase? Maybe you can communicate that goal more clearly, and why it's important, so that they can see that debating a new name for an object is distracting from that goal and should be reserved for another meeting.
    – LarsH
    Commented Nov 21, 2013 at 16:53
  • 57
    There's good advice in these answers. I would briefly add: consider using "process" as your ally. When someone says "this design is suboptimal" the correct response is "excellent, I'm glad you noticed that. After this meeting please enter a bug in the tracking database with a detailed description of the problem and your proposed fix. The triage team will review your proposal, prioritize it against the rest of the work items, and assign it to an appropriate developer to fix it once all the higher-priority items are fixed. Moving on..." Commented Nov 21, 2013 at 22:09

8 Answers 8


I think the problem is the task: "I have been tasked with teaching other teams a new codebase".

You have been given the wrong job, or maybe misinterpreted the job you've been given.

By presenting at the code level, you invite code level thinking.

Start at the system level and present the design and the design choices that were made. Don't allow extended discussion: you are not reviewing it. Do allow questions: you do want them to understand the system. If people "would have done it differently", fine. Maybe agree. Or not. But move on. It's the way it is right now.

When you get to the code level, you will have already got them primed with the system terminology. The names (I assume) will make sense. Same as above: no extended discussion, questions for understanding. Move on.

Now set some class problems to work through. How can we make enhancement X? Choose something non-trivial that "goes with the flow" of the system design, and work through what you would change. They should be getting the rationale of the system now. Choose another enhancement that could break the system if done wrong, and show how it can be done right. That should be an Ah Ha moment for them. Some might even beat you to it!

It's a tough gig, especially after the false start you've had. Sounds like you've invested a lot of time and effort already, and maybe there is a bit of a me versus them feeling. 'Fess up, and start again. We assume that they are smart people. Give them the challenge of thinking at the higher level. And break up the groups that already exist by selecting different cross sections of teams for the new sessions.

  • 3
    I have done a bit of high level design instruction first, as well as training on some new/unfamiliar technologies (IoC containers, dynamics) to help prep. That training has gone pretty well. It is a good point to raise.
    – Telastyn
    Commented Nov 21, 2013 at 3:49
  • +1 fot not trying to fight with people with "psychic hacks" like "I'll answer your off topic questions in the and at your time!" but rather changing the point of view
    – Buksy
    Commented Nov 23, 2013 at 12:05
  • 3
    Fantastic answer. I especially like the suggestion of making the focus be 'what it does' rather than 'what its internal components are named'. Commented Nov 27, 2013 at 14:38

"Park them". At the start of the lesson, explain what you are to discuss, and clearly explain what is considered Off Topic. If you are asked a question that is clearly OT, say so and move on. If they come back to it, write the question on a whiteboard (This is critical) for later discussion and move on. At the end of the lesson, when they are on their own time, not yours, watch how quickly those questions get resolved.

  • 8
    +1 That way people feel they are not being ignored.
    – andy256
    Commented Nov 21, 2013 at 3:44
  • I agree with this. IF the problem is discussing irrelevant things for too long then don't discuss irrelevant things...
    – Chris
    Commented Nov 21, 2013 at 9:31
  • 7
    Maybe rather than taking everyone's time by writing OT questions on a whiteboard, ask the questioner to take note of it (on a designated wiki page, JIRA issue, wherever).
    – LarsH
    Commented Nov 21, 2013 at 16:55
  • 14
    I think the physical act of taking a moment to write their question on the whiteboard clearly shows the questioner that you're deferring their question (rather than ignoring it) and shows to the rest of the audience who is asking all the questions and thus delaying progress. Commented Nov 21, 2013 at 17:15
  • 1
    @LarsH - exactly. By putting on the white board, for all to see, the conversation is stopped. If it comes up again, the instructor just points to the question and says "I promise we will come back to it".
    – mattnz
    Commented Nov 23, 2013 at 6:41

Set expectations correctly and be honest, open and upfront.

Make sure your goals are open and transparent.

Start off discussions with the high level view as promoted by andy256 (+1) but also make sure that you include your objectives, e.g.

"...as we look at this issue, lets make sure we don't focus on x, y and z. Let also make sure that we're not looking at at implementation details such as a,b,c or trivial details such as j,k,l. I know there's bound to be a lot of details in the code and details things that could be addressed, improved or made more standard, but lets try and look at what it's really achieving at a higher level first"

  • +1 for the first 2 sentences. However, telling people to not think of something is not a good way to get them to not think about it. "Whatever you do, don't think about pink unicorns." Before I mentioned pink unicorns, were you thinking about them? Probably not. If instead I said "Lets not get distracted by imaginary animals and instead focus on Australian animals" then koalas and kangaroos might have occurred to you, but probably not pink unicorns. Commented Nov 22, 2013 at 4:14
  • Good point. However the real point is not to stop people thinking (and not said) but to avoid people getting into those protracted conversations that are meeting killers and morale suckers. People will always think a lot of unsaid stuff. That's ok. In a professional business situation some things are said and many not. Commented Nov 22, 2013 at 4:23

So how do you educate other programmers enough that they stop fixating on trivialities and can meaningfully contribute to the design?

First, don't think of their concerns as "trivialities" or "bikeshedding". Those are judgmental words, and they're insulting. Their concerns are valid. They're just not important at the moment.

The key to any good meeting is for everyone to know:

  • why you're having a meeting and
  • what you hope to get out of it
  • how long it should last

State these things up front, explicitly, and explain the goals.

For example, you might say: "This meeting is for me to familiarize you with the Foo package and how it's used in our reporting module. My goal is to have you understand enough about Foo that you can work on the Bar Reports project coming up next week. I'd like us to be done in the next 90 minutes."

Then, when a topic comes up, it might go like this:

New person: "Why is FooWidget implemented as a facade pattern?"

You: "Well, I think it's because (short explanation of design decision)" or "I don't know."

If the answer is enough, that's great. If not, and it continues:

NP: "Don't you think it would be better done as a singleton?"

You: "I hadn't really thought about it, but I'd like to keep moving ahead with explaining how FooWidget works."

NP: "But if it's done as a singleton then we can--"

You: "I'm sorry to interrupt, but I need to keep this focused on how FooWidget works. This meeting is only scheduled until 11:00 and we have a lot to get through. The design discussion will have to wait for another time."

After you go through that once or twice, you can shorthand it to "That's outside the scope of this meeting."

Note that you are not saying "That's dumb to worry about" or "It doesn't matter" or "Shut up" or "You're too new to have input." You're simply focusing the meeting on what needs to get done and the time involved.

  • 1
    It easy to tell when a presenter really is not interested in feedback. Those meetings go fast. No one cares. Commented Nov 22, 2013 at 4:47

In certain organization you are never going to be able to achieve this. Many organizations value political wrangling and ladder-climbing way more than intellectual capacity, diligence, and loyalty. And why wouldn't they. Ladder-climbing puts people in positions of power, allows them to enhance their personal lives with more discretionary income and really never becomes obsolete.

Contrast this power-wrangling with actual problem solving, abstract thinking, and making decision on tough issues that they may be responsible for the consequences of later, and many employees weigh heavily on the side of trying to bikeshed as much as possible.

The only advice I suggest is that you make it crystal clear, in the context of your organization, if possible, that these participants personal fate depends on their comprehension, contribution, and effort toward the real problem you are trying to solve. If that's the enterprise architecture, expressed in this -errant-codebase and all it failures, that's it. Make it clear to them that they must provide substantial meaningful input about that. Not some other randomness, that happens to be a pet-peeve of a senior somebody or other and will gain them nice brownie-points by agreeing with said senior somebody on.

This is often hard to do, as the senior somebody usually doesn't understand the technology going on, isn't interested, and unfortunately, controls the raw-ingredients: employee time; hire & fire, conference room politics, promotions, etc., etc. seriously, et cetera to the nth.


What you call bikeshedding, I would call converting someone's flow of thoughts into our own. By discussing names, patterns, they get to understand the code into their own terms and there isn't any way to prevent it, it is needed.

Besides, there isn't any need to go for a very detailed walkthrough of a whole codebase, because details will be forgotten long before they get to work on it.

Based on these two ideas, I would suggest to break up the code base into units, and the learners into two-people groups. For each unit of code, each group will have, say 25 minutes (depends on the LOC of course), to be able to do a 5-10 minutes walkthrough of the code to the others. Three minutes of questions and repeat with the next unit. Explain is the key word; they have to ensure the others have understood all of it.

You would be only there to enforce time, no off-topic and control the unit has been understood enough. They will be actors of their learning and will be more focused on explaining to the others than bikeshedding.

You may require a high-level hand drawn schema from them of the code unit, which will be copied and kept on the team-shared documents, so they have something tangible to refer to in the future. That's good to anchor memories too.

Sorry if you have already tried that...


Have you tried making pre-lessons that people look over individually?

Make short videos or presentations that explain the content, how the code works, or basically all that you want to teach them in a format where they need to look at it on their own and learn the information you are trying to teach them.

Then you use the team-based sessions to discuss issues related to the content. You need to distinctly identify that the team sessions are for discussing and troubleshooting issues related to the content only.

If you provide the lessons to people on an individual basis, you may be able to avoid that other social issue where a single matter can become the voice of the group as a collective and distract away from the actual purpose of the lessons.

  • 13
    Nooo......., not videos..... "Death By Powerpoint" has been superseded by an even worse fate......, Although it will have the desired effect of stopping questions - threaten them with more videos that take 10 minutes to explain what can be read in 30 and understood in seconds....
    – mattnz
    Commented Nov 21, 2013 at 3:38
  • 6
    +1 mattnz Communication issues are unlikely to be improved with one-way interactions. Commented Nov 21, 2013 at 3:41
  • 1
    I don't want to be paused even if I'm in a video! What video format/codec disables pausing? :) :) :)
    – Kaz
    Commented Nov 21, 2013 at 6:23

Try teaching them the design of the codebase first, guide them round the architecture, BEFORE you start looking at specific examples. That way they might see how the code examples you look at fit into the bigger picture. Think about how your training programme is structured. And include the business motivation behind the design.

I spent several years training other developers, and I never went into the code before showing them how the system fitted together. Then when I got them doing code exercises in the framework the questions were structured and on-topic.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.