CS 257: Software Design

Code review: books

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 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 of the software in question.

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

• By Monday, 10/4, I will send you the repository links for each team in your code review session.
• Pick three teams at random from your group (not including your own). You will study the code for those three teams. Do something like this to really randomize your selection:
  $ python3 ... >>> import random >>> random.sample(['alice', 'bob', 'chuck', 'deirdre', 'eve'], 3) ['eve', 'bob', 'alice'] >>>
• For each of the three teams whose code you've selected to study:
  • 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 three teams, write up the highlights of your notes in this structure:
  • 2 or 3 things you like about their code, that you think they should keep doing.
  • 2 or 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 comments concise. These writeups should be short (typically less than one page) and as simple as you can make them. Also, consider the notes below on providing constructive feedback as you complete your write-up. Your notes will be shared with the authors of the code.
• After the code review sessions, send each of your three write-ups to me (Jeff) and to the authors of the code you're reviewing via Slack direct message.

During the code review

• You can expect us to use a full hour, and about 10 minutes per team. It's possible that we won't have time to discuss everybody's code. If that happens, I'll give feedback to the teams we missed either in person or in writing later that day.
• I will lead the process, including running the computer displaying the code, but I will want all of you to contribute your ideas, so be ready to chime in when I ask for your comments.
• IMPORTANT: When your code is being reviewed, it's important for you to just listen, and not to try to explain. We may ask you questions, or we may not, but please, speak only to give brief answers to direct questions. THIS IS HARD! You'll want to justify your choices, explain how you ran out of time, etc. Please resist these impulses.
• When you're giving feedback, keep your comments friendly, but brief.

How to help, 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. But you can also learn, so pay attention; 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 some fun learning together!