|
| 1 | +# General style for Jupyter Notebooks |
| 2 | + |
| 3 | + |
| 4 | +## Markdown |
| 5 | + |
| 6 | + |
| 7 | + |
| 8 | +### General style |
| 9 | + |
| 10 | +- File title is in Title Case, starts with a single digit, and uses underscores to separate between words. We follow APA Style Guide for capitalization: https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case. This means you should not capitalize minor words. |
| 11 | +- Notebook title is H1 and includes Workshop Name: Subtitle |
| 12 | +- Keep the scaffolding at the top and bottom of the template notebook intact |
| 13 | +- Use H1 for main headers that are referred to in the "Sections" section. |
| 14 | +- All headers are in Title Case. We follow APA Style Guide: https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case. This means you should not capitalize minor words. |
| 15 | +- Use H2 for subsections. These do not need to be linked to in the "Sections" section at the top of the notebook. |
| 16 | +- Use H3 headers for subsubsections. Don't go lower than H3 if you can avoid it. |
| 17 | +- Use emoji specified in the "Icons Used in This Notebook" section |
| 18 | +- Keep narrative text limited! |
| 19 | +- Avoid discussion of edge cases or caveats. |
| 20 | +- Use colloquial language and minimal jargon; if you need it, explain it. |
| 21 | +- Use **boldface** to highlight key concepts and important terms, but use it sparingly. |
| 22 | +- Don't use italics. |
| 23 | +- Use en-dash for lists. |
| 24 | +- Use `code font` for anything in code like variables, functions, and packages. |
| 25 | +- Use `code font` for menu items and UX pathways (like `Restart Kernel` or `Kernel-> Restart`) |
| 26 | +- Use `code font` for data frame rows/columns. |
| 27 | +- When discussing functions, include the trailing parentheses (e.g. `print()`). |
| 28 | +- When discussing methods, include the dot (e.g. `.sum()`). |
| 29 | +- Consistently use emoji for relevant sections. See below for some examples. |
| 30 | + |
| 31 | +### Learning Objectives |
| 32 | +- At least 3, max 6 per notebook. |
| 33 | +- Keep them short – one line each. |
| 34 | +- Use [learning objective verbs](https://swcarpentry.github.io/swc-releases/2016.06/instructor-training/20-lessons/). E.g. "Distinguish between the main data types in Python." |
| 35 | + |
| 36 | +### Challenge |
| 37 | +- Challenges are typically formatted as H2 / subsection (##). |
| 38 | +- Challenges use the 🥊 Boxing Glove emoji in the header. |
| 39 | +- Try to have at least one exercise every 15 minutes of instruction. More is better. A two-hour workshop needs at least **six challenges**. |
| 40 | +- Challenges have names, and are numbered. You should reference those names in the Solutions file. |
| 41 | +- Plan around 8 minutes for each challenge (including discussion of the solution and questions). |
| 42 | +- Don't use "Bonus Challenges" or the like. If really needed, use a "Take-Home Challenge" (1 max!) so it's clear these can be completed outside the workshop. |
| 43 | +- Copy filled-in challenges over to a solutions notebook that goes into the "solutions "folder. |
| 44 | +- See the Jupyter notebook template for an example. |
| 45 | +- Code cells in Challenges are two lines. The first says `# YOUR CODE HERE`, the second is empty. |
| 46 | +- Code cells in Challenges can be scaffolded. Use three dots (...) to indicate scaffolding. |
| 47 | + |
| 48 | +### Tip |
| 49 | +- Tips can be formatted as subsection (##) when they're more substantial. |
| 50 | +- Tips can be used without header when they are less substantial. |
| 51 | +- Tips use the 💡 Electric Light Bulb Emoji in the header / at the start of the line, followed by boldface **Tip:**, followed by the tip. |
| 52 | +- Tips are not numbered. |
| 53 | +- Keep them short and to the point. |
| 54 | +- See the Jupyter notebook template for an example. |
| 55 | + |
| 56 | +### Question |
| 57 | +- Questions are used without header. |
| 58 | +- Questions use the 🔔 Bell Emoji at the start of the line, followed by boldface **Question:**, followed by the question. |
| 59 | +- Questions are short queries about code or concepts. |
| 60 | +- Questions do not require participants to enter code. |
| 61 | +- Questions can be used as attention checks, and discussed during the workshop. |
| 62 | +- See the Jupyter notebook template for an example. |
| 63 | + |
| 64 | +### Warning |
| 65 | +- Warnings are used without header. |
| 66 | +- Warnings use the ⚠️ Warning Sign Emoji at the start of the line, followed by boldface **Warning:**, followed by the warning message. |
| 67 | +- Warnings act as short reminders to participants of common mistakes and errors. |
| 68 | +- See the Jupyter notebook template for an example. |
| 69 | + |
| 70 | +## Poll |
| 71 | + |
| 72 | +- Polls refer to Zoom polls, which can be used as a form of formative assessment. |
| 73 | +- Talk to D-Lab staff if you want to create Zoom polls before adding them in the notebook. |
| 74 | +- Polls use the 📝 memo enoji at the start of the line, followed by boldface **Poll**, followed by the name of the poll. |
| 75 | +- Polls are named with the format {workshop name}{workshop part - poll number} |
| 76 | +- make sure to check if they are **activated** by clicking "Polls/Quizzes" in Zoom. |
| 77 | +- Polls are used without header. |
| 78 | + |
| 79 | +### Demo |
| 80 | +- Demos can be used at the end of a notebook to show / highlight some advanced functionalities outside the scope of the workshop. |
| 81 | +- Demos use the 🎬 Clapper Board Emoji at the start of the header. |
| 82 | +- Demos are written as main sections (#) that are linked to in the "Sections" section. |
| 83 | +- Demos can used once per notebook. |
| 84 | +- Demos can be used to enthuse participants, and to point them to relevant other D-Lab workshops. |
| 85 | +- Demos are meant to be short: 5-10 mins max. |
| 86 | + |
| 87 | +### Key Points |
| 88 | +- Key Points are at the bottom of the notebook. |
| 89 | +- Key Points recap the most important concepts and ideas covered. |
| 90 | +- Use at least 3 and at most 8 Key Points. |
| 91 | + |
| 92 | + |
| 93 | +## Python style |
| 94 | + |
| 95 | +We follow [PEP](https://peps.python.org/pep-0008). This guide summarizes some of what's in there. |
| 96 | + |
| 97 | + |
| 98 | +### Indentation |
| 99 | + |
| 100 | +``` |
| 101 | +# Correct: |
| 102 | +
|
| 103 | +# Aligned with opening delimiter. |
| 104 | +foo = long_function_name(var_one, var_two, |
| 105 | + var_three, var_four) |
| 106 | +
|
| 107 | +# Add 4 spaces (an extra level of indentation) to distinguish arguments from the rest. |
| 108 | +def long_function_name( |
| 109 | + var_one, var_two, var_three, |
| 110 | + var_four): |
| 111 | + print(var_one) |
| 112 | +
|
| 113 | +# Hanging indents should add a level. |
| 114 | +foo = long_function_name( |
| 115 | + var_one, var_two, |
| 116 | + var_three, var_four) |
| 117 | +``` |
| 118 | + |
| 119 | +### Imports |
| 120 | + |
| 121 | +Imports are always put at the top of the cell. Imports should usually be on separate lines: |
| 122 | + |
| 123 | +``` |
| 124 | +# Correct: |
| 125 | +import os |
| 126 | +import sys |
| 127 | +# Wrong: |
| 128 | +import sys, os |
| 129 | +``` |
| 130 | + |
| 131 | + |
| 132 | +### Strings |
| 133 | + |
| 134 | +In Python, single-quoted strings and double-quoted strings are the same. We do |
| 135 | +not make a recommendation for this. Pick a rule and stick to it. When a string |
| 136 | +contains single or double quote characters, however, use the other one to avoid |
| 137 | +backslashes in the string. It improves readability. |
| 138 | + |
| 139 | + |
| 140 | +### Whitespace |
| 141 | + |
| 142 | +Avoid extraneous whitespace in the following situations: |
| 143 | + |
| 144 | +- Immediately inside parentheses, brackets or braces: |
| 145 | + |
| 146 | +``` |
| 147 | +# Correct: |
| 148 | +spam(ham[1], {eggs: 2}) |
| 149 | +# Wrong: |
| 150 | +spam( ham[ 1 ], { eggs: 2 } ) |
| 151 | +``` |
| 152 | + |
| 153 | +- Between a trailing comma and a following close parenthesis: |
| 154 | + |
| 155 | +``` |
| 156 | +# Correct: |
| 157 | +foo = (0,) |
| 158 | +# Wrong: |
| 159 | +bar = (0, ) |
| 160 | +``` |
| 161 | + |
| 162 | +- Immediately before a comma, semicolon, or colon: |
| 163 | + |
| 164 | +``` |
| 165 | +# Correct: |
| 166 | +if x == 4: print(x, y); x, y = y, x |
| 167 | +# Wrong: |
| 168 | +if x == 4 : print(x , y) ; x , y = y , x |
| 169 | +``` |
| 170 | + |
| 171 | +Always surround these binary operators with a single space on either side: |
| 172 | +assignment (=), augmented assignment (+=, -= etc.), comparisons |
| 173 | +(==, <, >, !=, <>, <=, >=, in, not in, is, is not), Booleans (and, or, not). |
| 174 | + |
| 175 | + |
| 176 | +### Comments |
| 177 | + |
| 178 | +Comments that contradict the code are worse than no comments. Always make a |
| 179 | +priority of keeping the comments up-to-date when the code changes! |
| 180 | + |
| 181 | +Comments should be complete sentences. The first word should be capitalized, |
| 182 | +unless it is an identifier that begins with a lower case letter (never alter |
| 183 | +the case of identifiers!). |
| 184 | + |
| 185 | +Block comments generally consist of one or more paragraphs built out of complete |
| 186 | +sentences, with each sentence ending in a period. |
| 187 | + |
| 188 | +Don't use inline comments. |
0 commit comments