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¶
All code must be submitted in a notebook file (.ipynb or myst)
Code must run or have explicit questions and comments about what was done about the errors
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.Each code cell should exactly one conceptually complete step in terms of the analysis.
Nearly all code cells should have output in some form
Every code cell must be motivated by text in markdown before it
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)
the
printfunction can only be used when it improves the readability over using jupyter’s display, must be justifiedNo deprecated or dangerous code constructs without appropriate justification
All assignment questions must be answered in markdown cells, not Python comments
Notebook files may not have extraneous metadata in them, links cannot have trackers
Alternative libraries not taught in class can only be used in extensions and must be contextualized and justified.
All sources cited must be high appropriate for the given context.
Additional Style¶
Code should ahdere to PEP8
Markdown syntax should be used to enhance the readability of the text (eg not all headings, bullets where they make sense)
Best practices that are highlighted in class should be followed (this list will expand over the semester)