Books: code review

We will have our first code review session over Zoom during class time on Monday, October 3. You should prepare for the code review as an individual, though you may certainly talk to your classmates while preparing, if you wish.

Goals

• Study your classmates' solutions to the books assignment to see a variety of solutions to the same problem.
• Practice giving and receiving constructive feedback about code structure.

What's a code review?

Code reviews vary in structure, complexity, and formality, but they share a core idea: you can improve the quality of software and prevent long-term problems for a project by letting somebody other than its author read the source code and provide feedback. Good software teams pretty much universally use some form of code review process. In this class, we will do several code and design reviews, some of them followed by revisions.

In my experience, when all participants prepare well and treat each other respectfully, code reviews are tons of fun, and great learning opportunities for everyone. That's what I'm shooting for in our first code review this week.

Preparation

• Find your group on the Slack #announcements channel.
• Share the URL for the git repo you and your partner used.
• Study the code for the two other teams in your review session.

• For each of the other teams in your group:

  • Read the usage.txt file, and spend a short amount of time testing the program so you know what features the program has implemented. Do not spend a lot of time on this. The goal of the code review is to focus on the source code, not the functionality. They're related, of course, but don't get bogged down in the latter.
  • Read the source code. Take notes about things you like in the code, things you don't understand, things you have questions about, and things you think could be improved.

• For each of the other teams, write up the highlights of your notes in this structure:

  • 2-3 things you like about their code, that you think they should keep doing.
  • 2-3 things you think could be improved. Ideally, you should include suggestions on how to make those improvements, but sometimes, you won't be sure how to fix a particular thing.
  • [optional] If there are things about the code that you don't understand, or about which you have questions, you may include a couple of those items at the end of your writeup.

  Keep your writeups short and simple (typically quite a bit less than one page). Also, consider the notes below on providing constructive feedback. Your notes will be shared with the authors of the code.

During the code review

• Get the Zoom link from my office hours page
• Please show up on Zoom by 8:30. I'll give you a quick reminder of the plan and then get you into breakout rooms by 8:35.
• Once you're in your breakout room, pick one person who has all the teams' code conveniently available to share their screen.

• Plan to discuss each team's code for 10-15 minutes. For each team, do something roughly like so:

  • Open up their code on a shared screen.
  • Have a general conversation about what people liked about this team's program.
  • When it's natural, move the conversation into questions and suggestions for improvement.
  • When things are winding down, check to see whether anybody who hasn't spoken has anything to offer. Make sure everybody gets the chance to speak. If you are a quiet person, speak up anyway. Your ideas are valuable.
• I will pop into each breakout room for 5-10 minutes.
• IMPORTANT: When your code is being discussed, it's important for you to just listen, and not to try to explain. People may ask you questions, in which case go ahead and give very brief answers. THIS IS HARD! You'll want to guide people through your code, justify your choices, explain how you ran out of time, etc. Please resist these impulses and just listen.
• When you're giving feedback, keep your comments clear, concise, and friendly.

After the code review

Send via Slack direct message each of your writeups to Jeff and to the authors of the code you're reviewing.

How to help and not hurt

Even among people who trust each other and have strong existing relationships, having your code reviewed can be stressful. In a class situation like this, where we mostly don't know each other very well yet, it can be even more so. The benefits of code reviews can be huge, but only if they are run within a positive and supportive environment. Here are a few suggestions for creating and maintaining that kind of environment.

• Be respectful to your classmates. They deserve it.
• Be friendly, too.
• If you have both praise and suggestions to offer, start with the praise. For most people, that makes it easier for them to listen to and understand your constructive criticism.
• Don't show off. If you know some fancy technique or you have some clever suggestion, think first before sharing it. "Am I sharing this idea to help the person who wrote this code, or am I sharing it to look cool?" If it's to help, great! Speak right up. But if it's to look cool, you can just share it in writing. (Note in particular that if you speak to look cool, your attempt generally fails, and you just end up looking like a jerk.)
• Remember that we have a pretty wide range of past programming experiences in this class. Do you have less experience than your peers? You'll soon have a lot more experience, and in the meantime, you have an opportunity to learn a ton of stuff, which is exciting. Do you have more experience than your peers? Great—then you can help, and deepen your own understanding by explaining your thoughts. But you can also learn, so pay attention to your classmates; I learn at least a little something every time I participate in a code review, no matter whose code we're looking at.
• Code reviews can be a blast. Let's have fun learning together!