Day 21

For Next Time

• Read Think Python Appendix A to prepare for our conversation on debugging next class
• 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 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

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 18
• Solid documentation throughout, but especially the sections under review. Documenting Python Code: A Complete Guide is a helpful reference here (stuff on type hinting is interesting, but probably not necessary for your projects). Solid documentation 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:

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:

• 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.

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.