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 post your first 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:

We have created a Google form that you should use to allow 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.

  1. Go to your project repository on GitHub
  2. In the upper left, click on “[N] commits” to see your commit history.
  3. Find the commit for the point in time you’d like us to review (generally the most recent). Click the “<> - Browse the repository at this point in the history” button on the right.
  4. Navigate to the file you’d like us to review.
  5. Scroll down to the line number starting the section of code to review and click the line number. You should see the line highlighted in yellow.
  6. Copy the URL from your browser. It should end in an HTML anchor (e.g. #L45) referring to the line number.