(This is a snapshot of my old weblog. New posts and selected republished essays can be found at raganwald.com.)
Thursday, July 15, 2004
An Email Explaining a Code Review
From: Reg Braithwaite-Lee
To: F---- S-------
Subject: An hour before your first Code Review at XXX
F---- :
In about an hour you will be participating in one of the most important events in your career with XXX, your first code review.
Code reviews are the foundation of team software development. The Code Review is where we have an opportunity to synchronize on what's important, what's not important, how things should work, and how much progress we are making.
Other organizations have other paths to team software development. For example, some organizations take an autocratic approach. Your manager would normally review your code personally and dictate changes to you, possibly accompanied by explanations of why the changes are important. Such companies often have "style police," architects or managers that dictate programming conventions and audit code for compliance.
We aren't going to do that. Having the team review the code together means that we can discuss the code and we can also discuss what's important and why. It's an opportunity for peer to peer communication, which is way more important and valuable to us than dictates from managers.
So thanks, you're a part of something very important.
Now that I've explained the importance of this, I want to set your expectations correctly. We are probably going to come up with a lot of 'opportunities for improvement' with your code. Why?
Well, for starters, there's the number of eyes. You look at your code with two eyes. A group looks at it with twelve or twenty eyes or more. It's almost impossible for anything to be so perfect nobody can suggest an improvement. And quite frankly, if you're optimizing every algorithm, you may be working on perfection at the expense of goodness.
Another reason has to do with synchronizing our ideas of importance. Do you know what I think is important to the success of the project? You probably have an incomplete idea. I probably have an incomplete idea of what you think is important. T--, A--, E--, and S-- probably have other ideas.
Under the circumstances, there's probably no piece of code that would meet with everyone's approval. Quite likely, the code you write does a good job of expressing your idea of what's important. If you can express your own ideas, you are coding well.
Part of this review will be discussing what is important and why. That way, we will all share the same ideas. And the next piece of code you write will express those shared ideas. As will the next piece of code S-- or O-- writes.
I want to stress that developing software in a team environment is an ongoing process of refinement and improvement. It simply doesn't work to try to 'start at the finish.' For example, you could have taken the weekend, interviewed me extensively, and rewrote your code to express my ideas. But such a body of code wouldn't help the team learn and communicate.
So it's better for XXX that we 'follow the path' and 'take each step once.' And you're a big part of our next step.
Once again, thank you in advance.
From: Reg Braithwaite-Lee
To: F---- S-------
Subject: An hour before your first Code Review at XXX
F---- :
In about an hour you will be participating in one of the most important events in your career with XXX, your first code review.
Code reviews are the foundation of team software development. The Code Review is where we have an opportunity to synchronize on what's important, what's not important, how things should work, and how much progress we are making.
Other organizations have other paths to team software development. For example, some organizations take an autocratic approach. Your manager would normally review your code personally and dictate changes to you, possibly accompanied by explanations of why the changes are important. Such companies often have "style police," architects or managers that dictate programming conventions and audit code for compliance.
We aren't going to do that. Having the team review the code together means that we can discuss the code and we can also discuss what's important and why. It's an opportunity for peer to peer communication, which is way more important and valuable to us than dictates from managers.
So thanks, you're a part of something very important.
Now that I've explained the importance of this, I want to set your expectations correctly. We are probably going to come up with a lot of 'opportunities for improvement' with your code. Why?
Well, for starters, there's the number of eyes. You look at your code with two eyes. A group looks at it with twelve or twenty eyes or more. It's almost impossible for anything to be so perfect nobody can suggest an improvement. And quite frankly, if you're optimizing every algorithm, you may be working on perfection at the expense of goodness.
Another reason has to do with synchronizing our ideas of importance. Do you know what I think is important to the success of the project? You probably have an incomplete idea. I probably have an incomplete idea of what you think is important. T--, A--, E--, and S-- probably have other ideas.
Under the circumstances, there's probably no piece of code that would meet with everyone's approval. Quite likely, the code you write does a good job of expressing your idea of what's important. If you can express your own ideas, you are coding well.
Part of this review will be discussing what is important and why. That way, we will all share the same ideas. And the next piece of code you write will express those shared ideas. As will the next piece of code S-- or O-- writes.
I want to stress that developing software in a team environment is an ongoing process of refinement and improvement. It simply doesn't work to try to 'start at the finish.' For example, you could have taken the weekend, interviewed me extensively, and rewrote your code to express my ideas. But such a body of code wouldn't help the team learn and communicate.
So it's better for XXX that we 'follow the path' and 'take each step once.' And you're a big part of our next step.
Once again, thank you in advance.
Labels: agile
