|
| 1 | +# PEP recommendations |
| 2 | + |
| 3 | +## What is a PEP? |
| 4 | + |
| 5 | +Find out about the purpose of PEPs (Python Enhancement Proposals) on the [pep site](https://peps.python.org/pep-0001/). Short answer: These are documents helping to organize the evolution of the Python language in the community. |
| 6 | + |
| 7 | +You can find a list of PEPs [here](https://peps.python.org/). |
| 8 | + |
| 9 | +## What is PEP 8? |
| 10 | + |
| 11 | +[PEP 8](https://peps.python.org/pep-0008/) is a meta-PEP = a PEP about other PEPs. PEP 8 specifies Python styling do's and dont's. |
| 12 | + |
| 13 | +## PEP 8 summary |
| 14 | + |
| 15 | +1. Line length |
| 16 | +Don't write lines that are very long. Reason: Often you would use multiple windows next to each other and that makes it hard to read code (and possibly lead to introduction of bugs). |
| 17 | +PEP 8 recommends lines no longer than 79 characters, but 90 is also a good number. |
| 18 | + |
| 19 | +1. Alignment of code |
| 20 | +Make use of indentation when using continuation lines: |
| 21 | + |
| 22 | + foo = long_function_name(var_one, var_two, |
| 23 | + var_three, var_four) |
| 24 | + |
| 25 | + instead of |
| 26 | + |
| 27 | + foo = long_function_name(var_one, var_two, |
| 28 | + var_three, var_four) |
| 29 | + |
| 30 | + You may also use hanging indents |
| 31 | + |
| 32 | + foo = long_function_name( |
| 33 | + var_one, var_two, |
| 34 | + var_three, var_four) |
| 35 | + |
| 36 | +1. Break line before binary operator |
| 37 | + |
| 38 | + income = (gross_wages |
| 39 | + + taxable_interest |
| 40 | + + (dividends - qualified_dividends) |
| 41 | + - ira_deduction |
| 42 | + - student_loan_interest) |
| 43 | + |
| 44 | + instead of |
| 45 | + |
| 46 | + income = (gross_wages + |
| 47 | + taxable_interest + |
| 48 | + (dividends - qualified_dividends) - |
| 49 | + ira_deduction - |
| 50 | + student_loan_interest) |
| 51 | + |
| 52 | +1. Blank lines: |
| 53 | +- two blank lines after `import` statements |
| 54 | +- two blank lines between functions and classes |
| 55 | +- one blank line between methods of classes |
| 56 | + |
| 57 | + import os |
| 58 | + |
| 59 | + |
| 60 | + def greeting(): |
| 61 | + print("Hello world!") |
| 62 | + |
| 63 | + |
| 64 | + def goodbye(): |
| 65 | + print("See ya!") |
| 66 | + |
| 67 | + instead of |
| 68 | + |
| 69 | + import os |
| 70 | + |
| 71 | + def greeting(): |
| 72 | + print("Hello world!") |
| 73 | + |
| 74 | + def goodbye(): |
| 75 | + print("See ya!") |
| 76 | + |
| 77 | + and |
| 78 | + |
| 79 | + def something(): |
| 80 | + pass |
| 81 | + |
| 82 | + |
| 83 | + class MyClass: |
| 84 | + |
| 85 | + def my_method(): |
| 86 | + pass |
| 87 | + |
| 88 | + def some_other(): |
| 89 | + pass |
| 90 | + |
| 91 | + instead of |
| 92 | + |
| 93 | + def something(): |
| 94 | + pass |
| 95 | + |
| 96 | + class MyClass: |
| 97 | + def my_method(): |
| 98 | + pass |
| 99 | + def some_other(): |
| 100 | + pass |
| 101 | + |
| 102 | +1. Encoding: The source file should always use UTF-8 encoding, and preferably without non-ASCII characters. It also makes your code more general if you use English words for identifiers (function names etc.). |
| 103 | + |
| 104 | +1. Imports should be on separate lines: |
| 105 | + |
| 106 | + import os |
| 107 | + import sys |
| 108 | + |
| 109 | + and not |
| 110 | + |
| 111 | + import os, sys |
| 112 | + |
| 113 | +1. String quotes: Do either use `'` or `"` throughout your project - do not mix. For triple-quoted strings, always use `"`, so `"""` instead of `'''`. |
| 114 | + |
| 115 | +1. Whitespaces: |
| 116 | + - no whitespace in parantheses - do `{item: 1}`, don't ```{ item: 1 }``` |
| 117 | + - whitespace after comma - do `a, b`, don't `a,b`, but not if followed by a parenthesis - do `(a, b,)` don't `(a, b, )` |
| 118 | + - no whitespace before parenthesis - do `calc_this(x)` don't `calc_this (x)` |
| 119 | + - no trailing whitespaces |
| 120 | + - whitespace around operators (ie. `=, +, +=, ==, is, and`) except for keywords - do `(x=circle)`, don't `(x = circle)` |
| 121 | +1. Keep comments up-to-date when changing the code. Comments should be complete sentences with a capitalized first word (unless it is an identifier). Use English language preferably. |
| 122 | +1. Include docstrings - see below (PEP 257). |
| 123 | +1. Naming conventions: |
| 124 | +- package and module names: short all-lowercase, preferably no underscores (do `analysis.py`, don't `Analysis.py`; do `mypackage`, don't `my_package`) |
| 125 | +- class names: use CamelCase (do `MyClass`, don't `myclass`, `Myclass`, `MYCLASS`) |
| 126 | +- functions and variable names: use lowercase with underscore to increase readibility (do `my_function()`, don't `myfunction()`, `MyFunction()`; do `accuracy_param`, don't `accuracyparam`, `accuracy_PARAM`) |
| 127 | +- constants: all capital with separating underscore (do `MIN_THRESHOLD`, don't `Min_Threshold`) |
| 128 | +- never use `l, O, I` letter names because of their similarity with `1` and `0` |
| 129 | + |
| 130 | +1. Underscores: |
| 131 | +- avoid name clashes using a trailing underscore or synonym (`class_`) |
| 132 | +- single leading underscore for methods that should only be used "internally" (should not be made available to the package or class interface) |
| 133 | +- use two leading underscores to invoke name mangling for attributes that should not be used in subclasses of the parent class (`__only_parent`) |
| 134 | +- double leading and trailing underscores for "magic" objects (dunder methods) - `__init__`, `__str__` |
| 135 | + |
| 136 | + |
| 137 | +## What is PEP 257? |
| 138 | + |
| 139 | +[PEP 257](https://peps.python.org/pep-0257/) specifies styling of Python docstrings. |
| 140 | + |
| 141 | +## PEP 257 summary |
| 142 | + |
| 143 | +## PEP 20 |
| 144 | + |
| 145 | +The Zen of Python. Type `import this` in your Python console. |
0 commit comments