Record Your Communication In The Code

While an expert and a junior are PairProgramming, there exist two strong tendencies that it will become either a boring lecture or a one-man game -- the expert monopolizes the keyboard and never let the other drive it. It could be both-side's fault.

Communicate. Junior should ask wisely and Expert should answer wisely.

While communicating, however, they usually do it merely by speech and it's (hopefully) recorded only on their brains. The content of the communication is not shared by other team members; they have to repeat the time consuming process of asking/explaining/exploring the code over again.

Therefore, like in wiki, record and accumulate the communication and the knowledge into the source code. If the junior can't understand some bits of the code, and asks on it, the expert notices that he failed to make the code clear at every point, and the pair tries "together" to refactor the bits into a new method with an explanatory name (remember that when you use comments as the last resort, the code quality will improve much more) so that next time other pairs see the bits, there be no need to ask/explain/explore whatever but to learn fast.

It is usually considered time-wasting when a junior doesn't understand and asks on some part of the code. RTFM? No. Congratulations! You've found a hole in the code. Through dialogue, the pair deeply understands the hole, and fills it up lest the future travelling pairs get trapped in.

A: Why are we going this way? I don't understand. What's the intention?

B: Oh... I didn't know you wouldn't understand it. Good question. I think it's because of R.

A: Well, I don't quite get it.

B: Okay, watch me refactoring the part.

   (B tries to remove the hole)

A: Why does the caller method in the first place not reveal that clearly?

B: How is it if I change the bit of code like this...?

   (and some more talk refactoring the code together)

A: Well, but doesn't it violate OnceAndOnlyOnce?

   (and some more talk)

A: Now I understand it and the code seems better.

B: Okay. Let's record the rest of our communication in the code for the future travellers as well as for our learning -- writing down what we've learned is a nice practice.

(and the pair modifies the rest of the code so that it reveal the reason R clearly)

RecordYourCommunicationInTheCode (with DialogueWhilePairProgramming) showed its great benefits especially when there were lots of juniors but few seniors in the team.

--JuneKim

Shouldn't you LetTheJuniorDrive?

Discussion migrated to LetTheJuniorDrive.

Hmmmm... So, don't just ListenToTheCode; TalkToTheCode? (by putting your comments into variables, methods and (if you can't avoid it) comments).