Peer Review
1 The goals of review
1.1 Why review?
No programmer works in a vacuum. In industry settings, programmers work with colleagues on projects larger than any one person can complete by themselves. In open-source settings, many programmers collaborate with other people they may mever have met in person. Even in solo settings, programmers have the vast resources of the internet to search for tutorials, code snippets, libraries and advice to get their projects started. But how do you decide what code is "good" for your project?
In industry settings, it is very common to peer review code: that is, you present your work to your colleagues, who then give you feedback on its design, correctness, clarity, efficiency, security, or other qualities. In fact, in most places, your code must be reviewed before it is even allowed to be merged into the overall project. This practice is especially common in open-source projects, where project leaders are custodians of the codebase but may not themselves write the majority of the code. And the solo programmer might well need to review the code and hints they find online, to determine if that code is helpful to them.
1.2 When to review?
Reviewing code after it has shipped is a bit too late: imagine if engineers critiqued the design of an airplane design only after it was fully built and attempting to fly! Instead, the best time to review any design is as early as is feasible: after some careful thought has gone into it, but before any expensive decisions have been finalized.
1.3 What to review?
Starting from a specification of the problem (e.g. written in design documents),
Develop examples to build intuition about what the problem asks (e.g. sample inputs and outputs),
Then break down the problem into manageable-sized pieces, with crisp self-contained purposes (e.g. signatures and templates), and
Only then, actually write the final code.
(If this sounds remarkably like The Design Recipe, it should!)
Examples are concrete, making the problem easier to grasp.
Examples are mostly free-standing: they can often be understood in isolation from each other or from the implementation.
Well-written examples can’t refer to implementation details —
which might vary widely between different solutions. Before getting into a disagreement about how to implement a solution, examples help developers first agree on what the problem is asking.
Reading other examples might point out gaps in your own understanding of the problem!
This last point is key. Being a careful code reviewer helps both the author and the reviewer! The more effort you spend trying to understand another approach to a problem, the more insight you might gain into how you solve it yourself.
2 Peer review in this course
As with any other skill, learning how to review someone else’s code well takes practice. Accordingly, we will give you several opportunities throughout the course to do so. In particular, we are asking you to review code while an assignment is still in progress. Typically, you will be asked to do just one or two reviews each week:
2.1 Submitting "useful" examples
As assignments grow, the sheer number of plausible scenaiors can easily grow to the point where it’s infeasible to read them all. This is a key difference between examples and tests: examples are meant to guide intuition and understanding, while tests aim to be thorough and comprehensive checking that the code behaves properly.
When we ask you to submit examples for peer review on Mondays, we therefore
want you to submit a subset of your examples —
2.2 Reviewing peer examples
Your reviews in this course will typically focus on just two questions: how correct do you think the examples you see are, and how thorough do you think they are? Thoroughness is tricky, since after all, we’re asking you to limit the number of examples you submit. Focus on diversity of examples: if multiple examples seem to do the same thing, perhaps they didn’t all need to be seen and reviewed...
Writing your reviews should not take very long. Deciding what to write might well be a longer process, especially if the code you receive is hard to decipher. (Keep that in mind, as you submit your code for others to read!) Additionally, your reviews ought to be professional and constructive, rather than vague, misleading, or outright insulting. You will be graded on the quality of your review, and if the graders think it was inappropriate, it will be withheld from the recipient so as not to confuse them.
2.3 But what about plagiarism?!
So you’ve just finished reviewing another student’s submission, and they have much better examples than you’ve come up with, and you’re really tempted to copy their code. Fantastic – go ahead! If seeing another student’s code helps you fix your assignment for its final submission, then the review process has done it’s job: but make sure you attribute your new tests to that code review. (After all, you’ve already submitted your examples prior to seeing other students’ work, so we know what your original understanding was.)
However, if the code you reviewed includes more than just tests – solutions or code, for instance – try to ignore it, and email a professor.