Day 21

For Next Time

READMEs and Documentation

Every project should have a README file explaining what it does, how to run it, etc. On GitHub in particular, this is your project’s landing page and the first impression people will have of your work. The final project README rubric includes guidelines for constructing a good README file, and we can discuss other considerations in class.

Even though you are not yet done with your project and thus may not be able to complete every section of the project README, we’d like you to update your draft of the README today to help provide context for the code review exercise.

Code Reviews

For some motivation from everyone’s favorite site, please check out this quote from Jeff Atwood.

I believe that peer code reviews are the single biggest thing you can do to improve your code.

    – Jeff Atwood, Co-Founder of Stack Overflow


Code reviews are widely utilized in industry as a means to improve code quality. Often, code reviews will be required before finalizing any contributions to a software repository. For instance, a very common workflow for code reviews is to use Git branches for feature development, which are merged into the master branch only after detailed comments are provided and any issues are resolved. There are lots of good resources on code reviews (for instance, check out the link in the Jeff Atwood quote or a discussion of using code reviews with a team of sys admins).

For next class, we, the instructors, will be doing a review of your team’s code. The purpose of this review is a bit different than the code reviews described above, in that we are not seeking to find every last tiny error in the code. Rather, we will focus on providing course corrections and high-level feedback that can help you shape your work over the final weeks of the project. As such, we’d like you to engage with the following steps to frame your code review.

1) Prepare your repository for external readers and code review:

2) Point us in the right direction:

Fill out the code review framing form to help us to give you the most useful feedback possible. Please take a look at the survey so that you have a sense of what information we are asking for.

Some ideas for choosing code sections:

Ensure that each code section has sufficient documentation for a reviewer to figure out when it’s called, what it does, and how it does it.

In the survey we ask you to point us to specific sections of code. Check out the instructions on the Recipes page to see how to create links to your work on GitHub.