Project 3 Code Review

You have been assigned two or three other teams whose code you will review. In preparation, you need read over their source code and also build and run their program.

For each team you're reviewing:

1. Check out the team's Phase 2 code (replace the highlighted bits):

   git clone --depth 1 --branch phase_3_2 https://me@bitbucket.org/them/their_repo.git
   

2. Get together with your teammate(s) and read over the code. Make sure you study it carefully. Write down:

   • A short list (2 or 3 items) of the things you like best about their code.
   • A short list of questions, if any, you have about the code. For example, “how does that work?” or “why did you decide to do X instead of Y?”. Please avoid editorializing or passive-aggressive crypto-criticism; the next bullet point is where you should get at real critiques.
   • A short list (1 to 3 items) of the most important suggestions you can offer for the improvement of their code.

   You are going to give these notes to the other group, so make sure that they are clear, legible, constructive, and polite.

   Consider reading through Google's C++ and Java style guides, and providing feedback on code style with respect to these. Remember that, more than anything else, consistency and legibility are key. If a team violates the word of the style guide, but is internally consistent and produces clear code, then that's just fine. If they adhere to the letter of the style guide, but produce code that's inconsistently formatted or difficult to read, that's not okay.

3. Thorough testing isn't the point of this exercise, but you'll want to try running the program.

After you've reviewed all other teams' code, do the same for your own team.

• Each team takes a turn being in the spotlight. Plan for about 8 minutes per team (with the likelihood that some discussions will spill over to 10). Each room should have an official timekeeper, and it's critical that you move quickly on to the next team after ten minutes.
• At the start of each team's turn, one of that team's members should show their code on screen and be prepared to scroll to requested portions of the code. (For example, somebody might ask, “can we look for a minute at the update() function?”.)
• When it's your team's turn in the spotlight, your job is to listen and answer questions. Resist the urge to give explanations for why you did X or Y unless explanations are requested. You'll get a chance to revise and explain in your final product. Speak only when asked an explicit question; otherwise, concentrate on taking notes.
• When you are providing feedback to another team, your goal is to provide useful feedback. Feedback tends to be more useful if it is presented in a tone that doesn't make the recipient defensive, so be nice. (This is actually pretty easy. It's a simple, day-to-day application of the golden rule, and all of you know how to be nice people.) Remember that there are one or two other teams also providing feedback, so don't dominate the conversation.
• Sometimes, you might not have a lot of ideas for improvement of the code (maybe the other team's code is better than yours; that happens often). In such cases, it's helpful to just give a clear idea of what you found easy to understand and what you found confusing.
• When the session is over, each team giving feedback hands their written notes to the team being reviewed.

After all teams have been reviewed, we should have half an hour or so left in the class period. Come back to the classroom if you left, and we'll all recap together.