Course Style Guide#

Following a style guide is a common requirement in companies to make it so that code written by different people stays easy to read for everyone. Consistent style also makes it easier to onboard new developers join a project and contribute faster.

The following style guide serves as practice for you following a style guide, makes your work easier to read for grading purposes, and holds you accountable to learning deeply and demonstrating that you have learned well.

Hard Requirements#

Warning

All work must adhere to these requirements or it may receive no feedback or credit. Minor misses may receive warnings, but if submitted work does not appear to represent a good faith effort at adhering to this style guide, the only comment will be, “Follow the style guide on the next assignment”

  1. All code must be submitted in a notebook file (.ipynb or myst)

  2. Code must run or have explicit questions and comments about what was done about the errors

  3. Python comments (# comment text) inside code cells should only be used to explain complex code that is not explained in the course notes. Using such code requires a citation for the source.

  4. Each code cell should exactly one conceptually complete step in terms of the analysis.

  5. Nearly all code cells should have output in some form

  6. Every code cell must be motivated by text in markdown before it

  7. Every code cell’s output must be interpretted in a markdown cell (may be combined in one cell that explains the above and motivates the below)

  8. the print function can only be used when it improves the readability over using jupyter’s display, must be justified

  9. No deprecated or dangerous code constructs without justification

  10. All assignment questions must be answered in markdown cells

  11. Notebook files may not have extraneous metadata in them

  12. Alternative libraries not taught in class can only be used when attempting level 3.

Additional Style#

Important

Mistakes on these will get detailed feedback once and a “see previous feedback” a second time before the whole assignment receives no feedback.

  1. Code should ahdere to PEP8

  2. Markdown syntax should be used to enhance the readability of the text (eg not all headings, bullets where they make sense)

  3. Best practices that are highlighted in class should be followed (this list will expand over the semester)