Day 22

For Next Time

READMEs

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.

Exercise:

With your team, share your list of important README elements from the previous Reading Journal. Combine these with the guidelines from the final project README rubric and use them to improve your project’s README.

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.

Documentation

In case we haven’t said it enough, proper documentation is vital to your work. As a general guideline, (in addition to your README) you should have:

Documenting Python Code: A Complete Guide is a helpful reference here (stuff on type hinting is interesting, but probably not necessary for your projects).

One cool feature of docstrings is that Python can use them to automatically generate documentation. The tool that does this is called pydoc, and it is what is used when you call help() in Python.

Exercise:

Autogenerate documentation for your project using pydoc:

pydoc path/to/my_project.py

This will open a help file based on your docstrings (use q to quit). Make sure this help file would be adequate for someone using your code - try showing it to someone not on your team. Add to your documentation based on this feedback.

pydoc can also generate HTML documentation, which you can add to your project website if you like (not required). If you want to generate truly beautiful online documentation, check out Sphinx (the tool used to generate the Python documentation).

Style and Lint

As you move to more polished code that other people will read and contribute to, style and consistency count. For a poetic take on “Pythonic” code, try typing import this in Python.

The most definitive Python style guide is PEP8 (Python Enhancement Proposals are the mechanisms by which the language grows). It has a list of guidelines along with concrete examples - definitely worth a read.

Checking style rules is a good job for a computer, and one tool you can use to do this for you is pylint. “Linting” is the process of checking code without actually running it (think about picking pieces of lint off your sweater). You can even set this up to run continuously in your text editor as you write code.

Linting can even help you catch bugs. Check out this pylint output for “Bad Kangaroo” from Think Python chapter 17.

...
C:  1, 0: Missing module docstring (missing-docstring)
W:  4, 4: Dangerous default value [] as argument (dangerous-default-value)
C: 12, 8: Variable name "t" doesn't conform to snake_case naming style (invalid-name)
...

Using mutable types as a default argument? Dangerous indeed - watch out!

Exercise:

Run pylint or pep8 on your project code and analyze the results. You don’t need to fix everything, but it’s best to know what rules you’re breaking and why.

Organization

We previously discussed strategies for organizing large Python projects on day 16. Review that material if necessary, with your final project code in mind.

Exercise:

Review the current organization of your project code. Think about and sketch out how you intend to organize your work into modules grouping related code before the final submission. This should likely correspond strongly to your system architecture diagram.

As we previously noted, this type of major refactoring can create lots of merge conflicts if you are not careful. It is best to make sure everything is checked in first, do the exercise together as a team, and have test cases before and after the restructuring to make sure nothing breaks. Now might not be the right time to do the actual reorganization, and that’s OK.

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 used 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. (If you’d like to try out using branches in Git, go for it!)

There are lots of good resources on the nuts and bolts of implementing code reviews in different settings. Regardless of the technical details of the review, it’s important to remember that there is a person on the other side of the review, and to approach the exercise with respect and awareness of your own biases.

Starting with today’s class, course 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:

Work through the exercises above to prepare your project repository for the review. You should:

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 2-3 specific sections of code. Check out the instructions on the Recipes page to see how to create links to your work on GitHub.