How to introduce code to a colleague

Question

How do you go about introducing the codebase, which may be rather complex and tangled with a lot of "gotchas," to a new member of your team?

I think the easiest way would be to have the overall architecture laid out with diagrams, and take a couple weeks (or months) giving the new person well defined (and well scoped) tasks as he becomes more accustomed to the code.

However, as a consultant (and junior employee, at that,) I can't always have that either due to time constraints or team role designations. (I have been on this particular project twice as long as anybody else, so "junior" is in no way "knows less about the code/project.")

I've been tasked quite a few times now to introduce a new member to the project and code, and sadly each time I find I'm not much better at it than the one before. I love diagrams and pictures, but often feel that they don't adequately account for the complexity in a system. (What about all the little's "gotchas"?)

The project is getting to a point where we will be handing it off to the client, and to make things more challenging, the person I'll be doing a knowledge transfer with is essentially just out of college. (Not that I'm much better when doing knowledge transfers with senior developers.)

I attend a user group once a month and other opportunities as they arise, so I'm not unused to be being introduced to new topics, but feel my ability to replicate effective knowledge sharing woefully inadequate.

Any advice would be greatly appreciated. I am looking mostly for a guideline I can follow. For example: Where do you start? How do you proceed? How do you cover unfamiliar technologies or patterns on the listener's part without taking all day? Where do you tie in business logic vs. code-structure?

Thank you!

(As always, please feel free to edit the question as you see fit.)

Answer 1

Step one is of course to remove the "gotchas" from the code. Clear, concise, consistent code is easier to get into, work with, and debug.

Where do you start?

I ask the newcomer how they want to get into the codebase. Everyone learns differently. Some people like having little tasks to work with. Some like debugging existing code. Some want to see the code running to understand what it does. Some want to start at the entrypoint and just navigate around. Some want visio diagrams... No set pattern is going to work best for everyone.

How do you cover unfamiliar technologies or patterns on the listener's part without taking all day?

I avoid them. Let them be black boxes until the newcomer asks about them. Then provide just enough information to get the jist of it, with the hint that they can learn more on their own time, or ask later when the general stuff is more well known.

Where do you tie in business logic vs. code-structure?

I try not to. It's almost always better for the newcomer to learn on their own so that it sits in their mind in a structure more natural to their way of thinking.

One thing to remember is to keep the instruction short. People tend to check out pretty quickly, so any more instruction at that point just doesn't 'stick'. Show them things for 15-60 minutes (different people have different attention spans) then take a 5-30 minute break for them to process it.

Answer 2

In my experience a good way to bridge the gap between the broad overview an architecture diagram gives and the gritty details of actually working with the code is to do a drill-down of the system, i.e. what happens when a request arrives (for server code) or a user makes an input (for client code), then step by step explain all the layers of code that are involved.

Another way is a "guided tour" of the sourcecode, i.e. go through the packages/namespaces/modules/directories and explain what the code in each of them does in general. Of course this requires the code to be laid out somewhat logically.

Answer 3

You're not teaching them the code base, you're teaching them your job. Don't try to think what they might need, look at what you have actually needed to know when doing your job.

Pull up the last few months of bug tracker history, scrum user stories, status reports, and source control commits. What files did you touch the most? What code is most problematic? What tasks took you the longest? Chances are, if you haven't touched it in the last few months, it's not as important as you might think it is.

Look at the stack of printouts on your desk. Check your recent browser history. Look for saved emails you refer to frequently, contacts you use, documents you have downloaded. Some of the most useful references I have passed on to others are the notes I kept for myself when first learning or designing the system. What reference material is most useful to you?

Next pull up your known backlog. What things would you need to research in order to finish those tasks? What areas of code most likely contain the problem? Convey that information as if you were taking notes for yourself.

If you refer to charts or diagrams in your daily work, include those. If you've never bothered making one, it's probably not going to be that useful to your successor/colleague either.

One of the most difficult tasks when teaching is trying to put yourself in their shoes. In this case, you are in their shoes. Make the most of it.

Answer 4

Support work is the best, take an easy bug and walk them through the areas where it'll be found. they will quickly learn how the code fits together. Naturally, they'll be coming over to ask questions about this bug and the codebase, but they'll get there (and you'll get a bug fixed). Often its much easier to figure things out with examples, similarly, its easier to work out a codebase by running through it in a debugger.

If you are unsure of the code changes (or they are, typically I'd be uncertain of my code fixes until I'm familiar with the codebase) then you can review it before checkin.

Of course, your existing ideas of broad overviews and block diagrams are essential first steps.