Participation

Class Discussions

Students will be expected to actively participate during class and to meaningfully contribute to class discussions. In general, students should volunteer such participation (but may be involuntarily volunteered). As a part of this participation, students should attend every class session for the course. Participation itself is not graded, rather meaningful contributions to discussion are expected.

Code Reviews

One form of participation, both individual and group, will be in class code reviews. Each group will submit 150-200 lines of code (computed via sloccount) from their term project via CourSys by Friday at 10PM on scheduled weeks. I will curate the submissions and make code available to the class. Each student will critique code from one other project of my choice and submit their critique by 10PM the following Tuesday night (again via CourSys).

Reviews should include at least 5 points as discussed below and should not be superficial. You should expect a good review to take an hour to perform. Each point should identify a strength, weakness, or alternative in the code along with a justification of why you have come to such a conclusion. Simply noticing something trivial in the code will not count toward these 5 points. Observe, analyze, and justify.

We will then review and discuss the code on Thursday of each week. I will select up to two of the code samples submitted for discussion in class. The group that wrote the code will first spend 5-10 minutes explaining the code and its design in class. Next, all students assigned to review that code will spend 5-10 minutes together presenting their critiques in front of the class. Afterward, there will be an open floor for a short discussion about the code including trade offs made in the code, risks present, and how the code might be improved.

Note that I reserve the right to select any code from the term projects (or other sources) to assign for review; however, the above format gives groups the opportunity to select code that they found thorny or particularly displeasing to write. Alternatively, groups may present and explain designs that they found elegant. Note, all reviews may be sent out to the entire class. Keep them honest, but also keep them respectful. Also, do not include your name within your review. CourSys tracks that automatically.

The code that each group submits should compile and run. It does not to be entirely correct for all inputs, but it should be clear that the group has at least tried to execute the code and that it can achiece basic objectives. Design prototypes that provide executable scaffolding for project features are fine.

Code reviews will start roughly in week three or four.

Guidelines for code review

Initially, you may think that the sole purpose of code review is to identify defects. The actual value extends beyond that into [Bacchelli 2013]:

• Overall improvement of code
• Identifying alternative solutions
• Building a sense of shared ownership
• Transfering about what parts of a code base do or of team idioms
• Transparency & team awareness

Our in class reviews span multiple teams and will not cover all of these points; however, focusing on small, syntactic issues is less valuable overall. The five points that you identify for each sample should try to focus on:

Design issues

• Is the intent of the code clear?
• Does it have a clear, focused responsibility?
• Is it designed to be hard to misuse? Could confusion cause errors?
• Is the code appropriately idiomatic for the language (C++ in this case)?
• Does the design violate the principle of least astonishment[1]?
• Are there issues with coupling? (temporal, odd inheritance, leaky abstractions)
• Specifically, does the interface hide design details to ease its use?
• How might the code better handle change?
• Are there alternative designs that could provide better trade offs?
• Are there performance or security concerns that should be addressed?

Code construction issues

• Do all names make sense? (types, functions, variables, …)
• Is code needlessly repeated?
• Do comments clarify or just repeat what the code does?
• Is the API appropriately separated from the implementation?
• Are errors handled appropriately?
• Are invariants clearly expressed?
• Are control structures deeply nested?
• Are there broad stylistic issues?

Avoid focusing on purely superficial issues. In many cases, such issues can be handled by automated tools, and they are the least beneficial aspects of code review. They will not count toward your reviews.

Also, remember that code review is an egoless process. Please keep that in mind both while reviewing and while being reviewed.