CS 190: Software Design Studio (Spring 2015)

Code Review 1

In the first round of in-class code reviews, we will consider three major areas within your Tweeter implementations:

• HTTP request dispatching: the code that receives HTTP requests, parses them according to the HTTP protocol, extracts relevant information from the requests, and dispatches to a specific handler for each request. This includes parameter validation.
• Tweet management: the code that manages tweets, including code for reading and writing data from/to disk, managing the cache in main memory, and crash recovery.
• JSON generation: code that helps to create JSON output.

We will spend one class period on each of these areas, during which we will review the implementations from three different projects. First, the creating team will describe its implementation briefly, then a few other students will offer comments on the strengths and weaknesses of the implementation. Other class members are also welcome to offer comments. Once we have reviewed all three implementations, we'll compare them and talk about overall issues for this particular kind of code.

Presenters

The presenting team will spend about 10-15 minutes in class to address the following issues:

• For each of the classes involved in your implementation, describe the key idea(s) behind that class. In particular, describe the information and/or design decisions that are hidden within that class.
• Go over (briefly) a few key methods, discussing the API for each briefly, in order to give the audience a feel for what are the pieces within the class.
• Walk through a simple use case: for HTTP request dispatching, walk through the receipt and dispatching of a request; for tweet management, walk through the creation of a new tweet and the collection of tweets relevant for the home_timeline.json request; for JSON generation, walk through the creation of JSON for the results of a home_timeline.json request.
• Talk briefly about what you found hard and easy in designing your implementation.
• What are the strengths and weaknesses of your approach?

Reviewers

You must read over the relevant code before class using the appropriate issue on cs190codereview.appspot.com. You don't need to read the entire project (though you are welcome to if you wish); you only need to read the parts related to the area being reviewed. You should enter comments in the code review tool, but do not publish your comments yet. The comments are saved and you will be able to see them, but no one else will see them until you publish them. After we have discussed the relevant code in class, then you should publish your comments. The "right" number of comments to enter is probably in the range of 10-20, depending on the complexity of the code you are reviewing and the number of useful issues you can identify (but don't invent issues if you don't see 10 things to comment on).

Here are some things to think about as you review other people's code:

• How easy was it for you to find and understand the relevant code? Are the interfaces and algorithms clear? Does the documentation provide all the information you would need if you were going to make modifications to the existing code? Ideally there should be nothing that you find confusing. It may be easier for you to understand this code because you have already implemented something similar, so try to put yourself in the position of someone who doesn't already have experience with this particular application.
• How effective is the class decomposition? Are the classes appropriately thick, and do they hide information effectively? Can you think of alternate class decompositions that seem better (e.g. are the classes too thin? too thick?)
• Is the code simple and obvious? Identify the most complicated parts.
• Any of the other topics we have discussed in class are also fair game.

You will have about 5 minutes to present your code review in class. I suggest addressing the following issues:

• Overall, what did you like best about the code? Was there anything that you liked better than what you did in your own project?
• How effective are the abstractions in this implementation? Do the classes have simple interfaces? Is it clear what information is hidden by each class? Did you notice significant information leakage between classes?
• How could the code be changed to make it simpler and easier to understand? Be as specific as possible: for example, it may help to plug in your laptop and display particular code for the class to see.
• Pick an example or two of documentation that you thought was good, and documentation that was missing or could be improved.

You will only have about 5 minutes, so start with the things that are most important (your online code review can include additional comments that we didn't have time for in class).

Schedule

Here is the schedule for this round of reviews. Note: there will probably not be enough time for all of the reviewers for each project to present in class. However, you are still responsible for creating a review with the online tool and publishing it after the class discussion. Reviewers will present in the order listed below, up until we run out of time for each project.

Date	Topic	Presenters	Reviewers
Friday, April 24	HTTP handling	Jansson, Speiser	Burke, Platias, Chang, Marks
		Abuzaid, Huang	Cook, Ulrich, Deng, Puyat
		Chan, Guo	Safreno, Li, Diab, Rygaard, Zhang
Monday, April 27	Tweet management	Burke, Rygaard	Chang, Speiser, Safreno, Platias
		Cook, Marks	Zhang, Abuzaid, Diab, Jansson, Guo
		Li, Puyat	Deng, Chan, Huang, Ulrich
Wednesday, April 29	JSON generation	Chang, Ulrich, Zhang	Jansson, Marks, Li, Abuzaid
		Deng, Safreno	Huang, Puyat, Burke, Chan
		Diab, Platias	Guo, Rygaard, Cook, Speiser

Everyone should bring their laptop to class for the code reviews, so that you can browse the code online while we are discussing it.

CS 190: Software Design Studio (Spring 2015)
Stanford University