coding conventions for python - mcgill...
TRANSCRIPT
![Page 2: Coding Conventions for Python - McGill Universitymsdl.cs.mcgill.ca/people/shahla/misc/PythonConventions.pdf · Coding Conventions for Python Shahla Almasri (salmas1@cs.mcgill.ca)](https://reader030.vdocument.in/reader030/viewer/2022040823/5e6d571210ed497c3253230e/html5/thumbnails/2.jpg)
2
References
Most of the materials in this presentation are taken directly from:
G. van Rossum and B. Warsaw, “Style Guide for Python Code”, http://www.python.org/peps/pep-0008.htmlD. Goodger and G. van Rossum, “DocstringConventions”, http://www.python.org/peps/pep-0257.html
![Page 3: Coding Conventions for Python - McGill Universitymsdl.cs.mcgill.ca/people/shahla/misc/PythonConventions.pdf · Coding Conventions for Python Shahla Almasri (salmas1@cs.mcgill.ca)](https://reader030.vdocument.in/reader030/viewer/2022040823/5e6d571210ed497c3253230e/html5/thumbnails/3.jpg)
3
OutlineNaming ConventionsOrganizing importsIndentions and line lengthBreak linesWhite spaceProgramming RecommendationsCommentsDocumentation StringsExample
![Page 4: Coding Conventions for Python - McGill Universitymsdl.cs.mcgill.ca/people/shahla/misc/PythonConventions.pdf · Coding Conventions for Python Shahla Almasri (salmas1@cs.mcgill.ca)](https://reader030.vdocument.in/reader030/viewer/2022040823/5e6d571210ed497c3253230e/html5/thumbnails/4.jpg)
4
Naming ConventionsModule Names:– Short, lowercase names, without underscores.
Example: myfile.py
Class Names:– CapWords convention.
Example: MyClass
Exception Names:– If a module defines a single exception raised for all
sorts of conditions, it is generally called "Error". Otherwise use CapWords convention (i.e. MyError.)
![Page 5: Coding Conventions for Python - McGill Universitymsdl.cs.mcgill.ca/people/shahla/misc/PythonConventions.pdf · Coding Conventions for Python Shahla Almasri (salmas1@cs.mcgill.ca)](https://reader030.vdocument.in/reader030/viewer/2022040823/5e6d571210ed497c3253230e/html5/thumbnails/5.jpg)
5
Naming Conventions (cont.)Method Names and Instance Variables:– The “Style Guide for Python Code” recommends using
lowercase with words separated by underscores (example: my_variable). But since most of our code uses mixedCase, I recommend using this style (example: myVariable)
– Use one leading underscore only for internal methods and instance variables (i.e. protected).Example: _myProtectedVar
– Use two leading underscores to denote class-private names Example: __myPrivateVar
– Don’t use leading or trailing underscores for public attributes unless they conflict with reserved words, in which case, a single trailing underscore is preferrable (example: class_)
![Page 6: Coding Conventions for Python - McGill Universitymsdl.cs.mcgill.ca/people/shahla/misc/PythonConventions.pdf · Coding Conventions for Python Shahla Almasri (salmas1@cs.mcgill.ca)](https://reader030.vdocument.in/reader030/viewer/2022040823/5e6d571210ed497c3253230e/html5/thumbnails/6.jpg)
6
OutlineNaming ConventionsOrganizing importsIndentions and line lengthBreak linesWhite spaceProgramming RecommendationsCommentsDocumentation StringsExample
![Page 7: Coding Conventions for Python - McGill Universitymsdl.cs.mcgill.ca/people/shahla/misc/PythonConventions.pdf · Coding Conventions for Python Shahla Almasri (salmas1@cs.mcgill.ca)](https://reader030.vdocument.in/reader030/viewer/2022040823/5e6d571210ed497c3253230e/html5/thumbnails/7.jpg)
7
Organizing ImportsThey should be always put at the top of the file, just after any module comments and docstrings, and before module globals and constants. Imports should be on separate lines.Wrong: import sys, osRight: import sys
import os
The following is OK, though: from types import StringType, ListType
![Page 8: Coding Conventions for Python - McGill Universitymsdl.cs.mcgill.ca/people/shahla/misc/PythonConventions.pdf · Coding Conventions for Python Shahla Almasri (salmas1@cs.mcgill.ca)](https://reader030.vdocument.in/reader030/viewer/2022040823/5e6d571210ed497c3253230e/html5/thumbnails/8.jpg)
8
Organizing Imports (cont.)
Imports should be grouped in the following order with a blank line between each group of imports:– standard library imports– related major package imports– application specific imports
![Page 9: Coding Conventions for Python - McGill Universitymsdl.cs.mcgill.ca/people/shahla/misc/PythonConventions.pdf · Coding Conventions for Python Shahla Almasri (salmas1@cs.mcgill.ca)](https://reader030.vdocument.in/reader030/viewer/2022040823/5e6d571210ed497c3253230e/html5/thumbnails/9.jpg)
9
OutlineNaming ConventionsOrganizing importsIndentions and line lengthBreak linesWhite spaceProgramming RecommendationsCommentsDocumentation StringsExample
![Page 10: Coding Conventions for Python - McGill Universitymsdl.cs.mcgill.ca/people/shahla/misc/PythonConventions.pdf · Coding Conventions for Python Shahla Almasri (salmas1@cs.mcgill.ca)](https://reader030.vdocument.in/reader030/viewer/2022040823/5e6d571210ed497c3253230e/html5/thumbnails/10.jpg)
10
Indentions and Line Length
Indentions:– 2 spaces (no tabs!) – Avoid using more than five levels of indention.
Line length:– Maximum of 72 characters (never exceed 79
characters)– You can break a long line using “\”.
![Page 11: Coding Conventions for Python - McGill Universitymsdl.cs.mcgill.ca/people/shahla/misc/PythonConventions.pdf · Coding Conventions for Python Shahla Almasri (salmas1@cs.mcgill.ca)](https://reader030.vdocument.in/reader030/viewer/2022040823/5e6d571210ed497c3253230e/html5/thumbnails/11.jpg)
11
OutlineNaming ConventionsOrganizing importsIndentions and line lengthBreak linesWhite spaceProgramming RecommendationsCommentsDocumentation StringsExample
![Page 12: Coding Conventions for Python - McGill Universitymsdl.cs.mcgill.ca/people/shahla/misc/PythonConventions.pdf · Coding Conventions for Python Shahla Almasri (salmas1@cs.mcgill.ca)](https://reader030.vdocument.in/reader030/viewer/2022040823/5e6d571210ed497c3253230e/html5/thumbnails/12.jpg)
12
Break Lines
Leave one line between functions in a class.Extra blank lines may be used to separate groups of related functionsBlank lines may be omitted between a bunch of related one-liners.Use blank lines in functions, sparingly, to indicate logical sections.
![Page 13: Coding Conventions for Python - McGill Universitymsdl.cs.mcgill.ca/people/shahla/misc/PythonConventions.pdf · Coding Conventions for Python Shahla Almasri (salmas1@cs.mcgill.ca)](https://reader030.vdocument.in/reader030/viewer/2022040823/5e6d571210ed497c3253230e/html5/thumbnails/13.jpg)
13
OutlineNaming ConventionsOrganizing importsIndentions and line lengthBreak linesWhite spaceProgramming RecommendationsCommentsDocumentation StringsExample
![Page 14: Coding Conventions for Python - McGill Universitymsdl.cs.mcgill.ca/people/shahla/misc/PythonConventions.pdf · Coding Conventions for Python Shahla Almasri (salmas1@cs.mcgill.ca)](https://reader030.vdocument.in/reader030/viewer/2022040823/5e6d571210ed497c3253230e/html5/thumbnails/14.jpg)
14
White Space
Multiple statements on the same line are discouraged.
WRONG:if foo == 'blah': doBlahThing()
CORRECT:if foo == 'blah':
doBlahThing()
![Page 15: Coding Conventions for Python - McGill Universitymsdl.cs.mcgill.ca/people/shahla/misc/PythonConventions.pdf · Coding Conventions for Python Shahla Almasri (salmas1@cs.mcgill.ca)](https://reader030.vdocument.in/reader030/viewer/2022040823/5e6d571210ed497c3253230e/html5/thumbnails/15.jpg)
15
White Space (cont.)
No white space immediately before an open parenthesis.
WRONG: spam (1)
CORRECT: spam(1)
WRONG: dict ['key'] = list [index]
CORRECT: dict['key'] = list[index]
![Page 16: Coding Conventions for Python - McGill Universitymsdl.cs.mcgill.ca/people/shahla/misc/PythonConventions.pdf · Coding Conventions for Python Shahla Almasri (salmas1@cs.mcgill.ca)](https://reader030.vdocument.in/reader030/viewer/2022040823/5e6d571210ed497c3253230e/html5/thumbnails/16.jpg)
16
White Space (cont.)No white space inside parentheses, brackets or braces.WRONG: spam( ham[ 1 ], { eggs: 2 } )CORRECT: spam(ham[1], {eggs:2})
No white space immediately before a comma, semicolon, or colon.WRONG:
if x == 4 : print x , y ; x , y = y , x
CORRECT:if x == 4:
print x, y; x, y = y, x
![Page 17: Coding Conventions for Python - McGill Universitymsdl.cs.mcgill.ca/people/shahla/misc/PythonConventions.pdf · Coding Conventions for Python Shahla Almasri (salmas1@cs.mcgill.ca)](https://reader030.vdocument.in/reader030/viewer/2022040823/5e6d571210ed497c3253230e/html5/thumbnails/17.jpg)
17
White Space (cont.)No more than one space around an operator.
WRONG:x = 1yVal = 2longVariable = 3
CORRECT:x = 1yVal = 2longVariable = 3
![Page 18: Coding Conventions for Python - McGill Universitymsdl.cs.mcgill.ca/people/shahla/misc/PythonConventions.pdf · Coding Conventions for Python Shahla Almasri (salmas1@cs.mcgill.ca)](https://reader030.vdocument.in/reader030/viewer/2022040823/5e6d571210ed497c3253230e/html5/thumbnails/18.jpg)
18
White Space (cont.)Always surround the following operators with a single space on either side– assignment (=) – comparisons (==, <, >, !=, <>, <=, >=, in, not in, is, is
not)– Booleans (and, or, not)– Arithmetic operators (+, -, *, /, %)
WRONG:if (x==4)or(x==5):
x=y+5CORRECT:
if (x == 4) or (x == 5): x = y + 5
![Page 19: Coding Conventions for Python - McGill Universitymsdl.cs.mcgill.ca/people/shahla/misc/PythonConventions.pdf · Coding Conventions for Python Shahla Almasri (salmas1@cs.mcgill.ca)](https://reader030.vdocument.in/reader030/viewer/2022040823/5e6d571210ed497c3253230e/html5/thumbnails/19.jpg)
19
White Space (cont.)Don't use spaces around the '=' sign when used to indicate a keyword argument or a default parameter value.
WRONG:def complex(real, imag = 0.0):
return magic(r = real, i = imag)
CORRECT:def complex(real, imag=0.0):
return magic(r=real, i=imag)
![Page 20: Coding Conventions for Python - McGill Universitymsdl.cs.mcgill.ca/people/shahla/misc/PythonConventions.pdf · Coding Conventions for Python Shahla Almasri (salmas1@cs.mcgill.ca)](https://reader030.vdocument.in/reader030/viewer/2022040823/5e6d571210ed497c3253230e/html5/thumbnails/20.jpg)
20
OutlineNaming ConventionsOrganizing importsIndentions and line lengthBreak linesWhite spaceProgramming RecommendationsCommentsDocumentation StringsExample
![Page 21: Coding Conventions for Python - McGill Universitymsdl.cs.mcgill.ca/people/shahla/misc/PythonConventions.pdf · Coding Conventions for Python Shahla Almasri (salmas1@cs.mcgill.ca)](https://reader030.vdocument.in/reader030/viewer/2022040823/5e6d571210ed497c3253230e/html5/thumbnails/21.jpg)
21
Programming Recommendations
Comparisons to singletons like None should always be done with 'is' or 'is not‘.Wrong:
if x:y = 6
Right:if x is not None:
y = 6
Don't compare boolean values to True or False.Wrong:
if greeting == True:y = 6
Right:if greeting:
y = 6
![Page 22: Coding Conventions for Python - McGill Universitymsdl.cs.mcgill.ca/people/shahla/misc/PythonConventions.pdf · Coding Conventions for Python Shahla Almasri (salmas1@cs.mcgill.ca)](https://reader030.vdocument.in/reader030/viewer/2022040823/5e6d571210ed497c3253230e/html5/thumbnails/22.jpg)
22
Programming Recommendations (cont.)Avoid slicing strings when checking for prefixes or suffixes. Use startswith() and endswith() instead.Wrong:
if foo[:3] == 'bar':Right:
if foo.startswith('bar'):
![Page 23: Coding Conventions for Python - McGill Universitymsdl.cs.mcgill.ca/people/shahla/misc/PythonConventions.pdf · Coding Conventions for Python Shahla Almasri (salmas1@cs.mcgill.ca)](https://reader030.vdocument.in/reader030/viewer/2022040823/5e6d571210ed497c3253230e/html5/thumbnails/23.jpg)
23
OutlineNaming ConventionsOrganizing importsIndentions and line lengthBreak linesWhite spaceProgramming RecommendationsCommentsDocumentation StringsExample
![Page 24: Coding Conventions for Python - McGill Universitymsdl.cs.mcgill.ca/people/shahla/misc/PythonConventions.pdf · Coding Conventions for Python Shahla Almasri (salmas1@cs.mcgill.ca)](https://reader030.vdocument.in/reader030/viewer/2022040823/5e6d571210ed497c3253230e/html5/thumbnails/24.jpg)
24
CommentsBlock Comments:– They are indented to the same level as the code they
apply to.– Each line of a block comment starts with a # and a
single space.– Paragraphs inside a block comment are separated by
a line containing a single #. – Block comments are best surrounded by a blank line
above and below them
Example:# Compensate for border. This is done by incrementing x# by the same amount
x += 1
![Page 25: Coding Conventions for Python - McGill Universitymsdl.cs.mcgill.ca/people/shahla/misc/PythonConventions.pdf · Coding Conventions for Python Shahla Almasri (salmas1@cs.mcgill.ca)](https://reader030.vdocument.in/reader030/viewer/2022040823/5e6d571210ed497c3253230e/html5/thumbnails/25.jpg)
25
Comments (cont.)
Inline Comments:– They should start with a # and a single space.– Should be separated by at least two spaces
from the statement they apply to.
Example:x += 1 # Compensate for border
![Page 26: Coding Conventions for Python - McGill Universitymsdl.cs.mcgill.ca/people/shahla/misc/PythonConventions.pdf · Coding Conventions for Python Shahla Almasri (salmas1@cs.mcgill.ca)](https://reader030.vdocument.in/reader030/viewer/2022040823/5e6d571210ed497c3253230e/html5/thumbnails/26.jpg)
26
OutlineNaming ConventionsOrganizing importsIndentions and line lengthBreak linesWhite spaceProgramming RecommendationsCommentsDocumentation StringsExample
![Page 27: Coding Conventions for Python - McGill Universitymsdl.cs.mcgill.ca/people/shahla/misc/PythonConventions.pdf · Coding Conventions for Python Shahla Almasri (salmas1@cs.mcgill.ca)](https://reader030.vdocument.in/reader030/viewer/2022040823/5e6d571210ed497c3253230e/html5/thumbnails/27.jpg)
27
Documentation StringsWrite docstrings for all public modules, functions, classes, and methods.Docstrings are not necessary for non-public methods, but you should have a comment that describes what the method does. This comment should appear after the "def" line. Insert a blank line before and after all docstrings that document a class.
![Page 28: Coding Conventions for Python - McGill Universitymsdl.cs.mcgill.ca/people/shahla/misc/PythonConventions.pdf · Coding Conventions for Python Shahla Almasri (salmas1@cs.mcgill.ca)](https://reader030.vdocument.in/reader030/viewer/2022040823/5e6d571210ed497c3253230e/html5/thumbnails/28.jpg)
28
Documentation Strings (cont.)
One-line Docstrings:– The opening and closing """ are on the same
line.– There is no blank line either before or after
the docstring.– Describes the function or method's effect as a
command ("Do this", "Return that"), not as a description.
![Page 29: Coding Conventions for Python - McGill Universitymsdl.cs.mcgill.ca/people/shahla/misc/PythonConventions.pdf · Coding Conventions for Python Shahla Almasri (salmas1@cs.mcgill.ca)](https://reader030.vdocument.in/reader030/viewer/2022040823/5e6d571210ed497c3253230e/html5/thumbnails/29.jpg)
29
Documentation Strings (cont.)
Multi-line Docstrings:– The """ that ends a multiline docstring should be on a
line by itself.– Script: The docstring of a script should be usable as
its "usage" message. It should document the script's function, the command line syntax, and the environment variables.
– Module: The docstring for a module should generally list the classes, exceptions and functions (and any other objects) that are exported by the module, with a one-line summary of each.
![Page 30: Coding Conventions for Python - McGill Universitymsdl.cs.mcgill.ca/people/shahla/misc/PythonConventions.pdf · Coding Conventions for Python Shahla Almasri (salmas1@cs.mcgill.ca)](https://reader030.vdocument.in/reader030/viewer/2022040823/5e6d571210ed497c3253230e/html5/thumbnails/30.jpg)
30
Documentation Strings (cont.)
– Class:• The docstring for a class should summarize its
behavior and list the public methods and instance variables.
• If the class is intended to be subclassed, and has an additional interface for subclasses, this interface should be listed separately.
• If a class subclasses another class and its behavior is mostly inherited from that class, its docstring should mention this and summarize the differences.
• The class constructor should be documented in the docstring for its __init__ method.
![Page 31: Coding Conventions for Python - McGill Universitymsdl.cs.mcgill.ca/people/shahla/misc/PythonConventions.pdf · Coding Conventions for Python Shahla Almasri (salmas1@cs.mcgill.ca)](https://reader030.vdocument.in/reader030/viewer/2022040823/5e6d571210ed497c3253230e/html5/thumbnails/31.jpg)
31
Documentation Strings (cont.)
– Function or method:• The docstring should summarizes its behavior and
document its arguments, return value, side effects, exceptions raised, and restrictions on when it can be called.
• Optional arguments should be indicated. • Use the verb "override" to indicate that a subclass
method replaces a superclass method and does not call the superclass method; use the verb "extend" to indicate that a subclass method calls the superclass method.
• The docstring should contain a summary line, followed by a blank line, followed by a more elaborate description.
![Page 32: Coding Conventions for Python - McGill Universitymsdl.cs.mcgill.ca/people/shahla/misc/PythonConventions.pdf · Coding Conventions for Python Shahla Almasri (salmas1@cs.mcgill.ca)](https://reader030.vdocument.in/reader030/viewer/2022040823/5e6d571210ed497c3253230e/html5/thumbnails/32.jpg)
32
OutlineNaming ConventionsOrganizing importsIndentions and line lengthBreak linesWhite spaceProgramming RecommendationsCommentsDocumentation StringsExample