We will have our first code review session during your first Discussion Group meeting
this week. You should prepare 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
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
- On Saturday, 1/16, I will email you the repository links for each team in your
discussion group.
- Pick three teams at random from your discussion 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 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.
- Submit your write-ups using one of these surveys:
After the code review sessions, I will send your feedback to the other teams, with
your name attached. Of course, you will also receive written feedback from some of your
discussion group members.
During the code review
- You can expect us to use the full hour of our meeting time. It's also unlikely that we will have
time to discuss everybody's code. I'll pick the order in which we look at people's code.
- I will lead the process, including running a screen share 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!