Day 21

For Next Time

• Read Think Python Appendix A to prepare for Tuesday’s conversation on debugging
• Add README to your project repository, update your architecture diagram, make sure your code is documented
• Submit Code Review framing survey today (instructions below)

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
      (source: http://blog.codinghorror.com/code-reviews-just-do-it/)

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:

• Post project README file
• Update and post system architecture diagram that you worked on day 17
• Solid documentation throughout, but especially the sections under review. This means:
  • Docstring/header comment at the top of each file explaining what it does
  • Docstring for each class and (nontrivial) function
  • Comments for sections of code that are complex enough to need explanation
• Check project organization, make sure your files and folder names are logical, remove dead code (e.g., files or functions are no longer utilized) and non-project junk (e.g. .pyc files, generated program outputs)

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:

• code that you have questions about
• code that you want to show off
• code that you suspect may be fragile or buggy
• code that is particularly complicated

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.

How to link to a section of code in GitHub

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.