CS 204: Software Design

Web application: a small code review

On Wednesday, we will have a short code review session. For this session, each group will meet with one or two other groups to discuss each group's code. We will spend about half an hour total on this exercise, plus another few minutes for all-class discussion.

What to prepare

• Exchange the URLs for your groups' projects, and make sure everybody can see the source code as well as the running web application.

• Make sure there is at least one laptop in class per table on Wednesday.

• Read each group's code carefully. Once you have read the other group's (or groups') code, apply the same type of reading to your own group's code.

• For each group you are working with at the code review, 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. These questions can be of various types. For example, "how does that work?" is different from "why did you decide to do X instead of Y?"
  • A short list (1 to 3 items) of the most important suggestions you can offer for the improvement of their code.

  Make sure to write your notes in a way you would be willing to hand over to the other group. In particular, make sure your notes are legible, constructive, and polite.

What to do in your session?

• Each team takes a turn being in the spotlight. Plan for about ten minutes per team.

• 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. (e.g. somebody might ask "can we look for a minute at the main() 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.

• 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 are nice people.)

• 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, just giving a clear idea of what you found easy to understand and what you found confusing would be helpful.

• When the session is over, the team giving feedback should hand their written notes to the team being reviewed.