Skip to content

Instantly share code, notes, and snippets.

@tomschr

tomschr/python-checklist.md

Last active May 13, 2024 02:13
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save tomschr/c23585f6bcbeb6374f183deb83352f36 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save tomschr/c23585f6bcbeb6374f183deb83352f36 to your computer and use it in GitHub Desktop.
Download ZIP

Revisions

  1. tomschr revised this gist Mar 16, 2020. 1 changed file with 11 additions and 13 deletions.
    24 changes: 11 additions & 13 deletions python-checklist.md
    View file
    Original file line number Diff line number Diff line change
    @@ -9,31 +9,29 @@ It should help to overcome common pitfalls.

    1. Check your header of your file. It should contain:

    a. A shebang line `#!/usr/bin/env python3` if it's a script. Leave it out if you have a module or a package.
    a. Shebang line `#!/usr/bin/env python3` if it's a script. Leave it out if you have a module or a package.

    b. A docstring about the purpose of this file.
    b. File docstring about the purpose of this file.

    c. If needed, a list of imports; every import should occupy one line.
    c. If needed, a list of imports; every import should occupy one line. Use `isort` to keep them sorted.

    d. Some meta information like `__author__`, `__version__`, `__url__`.
    d. Meta information like `__author__`, `__version__`, and `__url__`.

    e. If needed, global constants in uppercase letters.

    1. Check if all your functions contain a docstring with the following
    properties:
    1. Check if all your functions contain a docstring with the following properties:

    a. a first line with the purpose of the function.
    a. First line with the purpose of the function.

    b. an empty line
    b. Empty line.

    c. one or more lines describing the arguments
    c. One or more lines describing the arguments.

    d. a line describing possible return values
    d. A line describing possible return values.

    e. a line describing possible exceptions
    e. A line describing possible exceptions.

    1. Keep your source code tidy. Why? Because, good looking source code is
    easier to read.
    1. Keep your source code tidy. Why? Because, good looking source code is easier to read and maintain.

    1. Follow PEP8. Use `black` or other source code formatters.

  2. tomschr revised this gist Mar 16, 2020. 1 changed file with 12 additions and 0 deletions.
    12 changes: 12 additions & 0 deletions python-checklist.md
    View file
    Original file line number Diff line number Diff line change
    @@ -12,17 +12,24 @@ It should help to overcome common pitfalls.
    a. A shebang line `#!/usr/bin/env python3` if it's a script. Leave it out if you have a module or a package.

    b. A docstring about the purpose of this file.

    c. If needed, a list of imports; every import should occupy one line.

    d. Some meta information like `__author__`, `__version__`, `__url__`.

    e. If needed, global constants in uppercase letters.

    1. Check if all your functions contain a docstring with the following
    properties:

    a. a first line with the purpose of the function.

    b. an empty line

    c. one or more lines describing the arguments

    d. a line describing possible return values

    e. a line describing possible exceptions

    1. Keep your source code tidy. Why? Because, good looking source code is
    @@ -38,8 +45,11 @@ It should help to overcome common pitfalls.
    1. Try to follow a naming convention for your variables:

    a. Use uppercase letters for global constants.

    b. Use an uppercase letter as first letter for classes.

    c. Use lowercase letters for all other variables.

    d. Use an underscore to indicate that a variable is "private".


    @@ -64,6 +74,8 @@ It should help to overcome common pitfalls.
    1. Use meaningful names for your function, classes, and variables:

    a. Be as specific as possible.

    b. Use nouns for classes and verbs for methods.

    c. Use only common names for temporary variables like `i`, `j`, `k`,
    `m`, `n` for integers and `c`, `d`, and `e`, for characters.
  3. tomschr revised this gist Mar 16, 2020. 1 changed file with 1 addition and 0 deletions.
    1 change: 1 addition & 0 deletions python-checklist.md
    View file
    Original file line number Diff line number Diff line change
    @@ -10,6 +10,7 @@ It should help to overcome common pitfalls.
    1. Check your header of your file. It should contain:

    a. A shebang line `#!/usr/bin/env python3` if it's a script. Leave it out if you have a module or a package.

    b. A docstring about the purpose of this file.
    c. If needed, a list of imports; every import should occupy one line.
    d. Some meta information like `__author__`, `__version__`, `__url__`.
  4. tomschr revised this gist Mar 16, 2020. 1 changed file with 5 additions and 5 deletions.
    10 changes: 5 additions & 5 deletions python-checklist.md
    View file
    Original file line number Diff line number Diff line change
    @@ -9,11 +9,11 @@ It should help to overcome common pitfalls.

    1. Check your header of your file. It should contain:

    a. A shebang line `#!/usr/bin/env python3` if it's a script. Leave it out if you have a module or a package.
    b. A docstring about the purpose of this file.
    c. If needed, a list of imports; every import should occupy one line.
    d. Some meta information like `__author__`, `__version__`, `__url__`.
    e. If needed, global constants in uppercase letters.
    a. A shebang line `#!/usr/bin/env python3` if it's a script. Leave it out if you have a module or a package.
    b. A docstring about the purpose of this file.
    c. If needed, a list of imports; every import should occupy one line.
    d. Some meta information like `__author__`, `__version__`, `__url__`.
    e. If needed, global constants in uppercase letters.

    1. Check if all your functions contain a docstring with the following
    properties:
  5. tomschr revised this gist Mar 16, 2020. 1 changed file with 1 addition and 2 deletions.
    3 changes: 1 addition & 2 deletions python-checklist.md
    View file
    Original file line number Diff line number Diff line change
    @@ -9,8 +9,7 @@ It should help to overcome common pitfalls.

    1. Check your header of your file. It should contain:

    a. A shebang line `#!/usr/bin/env python3` if it's a script. Leave it
    out if you have a module or a package.
    a. A shebang line `#!/usr/bin/env python3` if it's a script. Leave it out if you have a module or a package.
    b. A docstring about the purpose of this file.
    c. If needed, a list of imports; every import should occupy one line.
    d. Some meta information like `__author__`, `__version__`, `__url__`.
  6. tomschr revised this gist Mar 16, 2020. 1 changed file with 2 additions and 2 deletions.
    4 changes: 2 additions & 2 deletions python-checklist.md
    View file
    Original file line number Diff line number Diff line change
    @@ -51,6 +51,8 @@ It should help to overcome common pitfalls.

    1. Make sure that every of your functions fullfil only **one purpose**.

    1. Write "simple" functions.

    1. Try to limit the complexity of your code.
    Install the packages `python3-mccabe` and `python3-flake8` and run:

    @@ -65,5 +67,3 @@ It should help to overcome common pitfalls.
    b. Use nouns for classes and verbs for methods.
    c. Use only common names for temporary variables like `i`, `j`, `k`,
    `m`, `n` for integers and `c`, `d`, and `e`, for characters.

    1. Write "simple" functions.
  7. tomschr created this gist Mar 16, 2020.
    69 changes: 69 additions & 0 deletions python-checklist.md
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,69 @@
    # Programming Checklist for Clean Code in Python

    This checklist contains some tips and recommendations sorted into a syntax
    and a design category.

    It should help to overcome common pitfalls.

    ## Syntax

    1. Check your header of your file. It should contain:

    a. A shebang line `#!/usr/bin/env python3` if it's a script. Leave it
    out if you have a module or a package.
    b. A docstring about the purpose of this file.
    c. If needed, a list of imports; every import should occupy one line.
    d. Some meta information like `__author__`, `__version__`, `__url__`.
    e. If needed, global constants in uppercase letters.

    1. Check if all your functions contain a docstring with the following
    properties:

    a. a first line with the purpose of the function.
    b. an empty line
    c. one or more lines describing the arguments
    d. a line describing possible return values
    e. a line describing possible exceptions

    1. Keep your source code tidy. Why? Because, good looking source code is
    easier to read.

    1. Follow PEP8. Use `black` or other source code formatters.

    1. If you write a script, add a `if ___name__ == "__main__"` line at the
    end. This is needed to distinguish between a module and a script.

    1. Be pythonic. That's a broad topic, but usually pythonic code is clear code.

    1. Try to follow a naming convention for your variables:

    a. Use uppercase letters for global constants.
    b. Use an uppercase letter as first letter for classes.
    c. Use lowercase letters for all other variables.
    d. Use an underscore to indicate that a variable is "private".


    ## Design

    1. Import only those modules or packages that you really need.

    1. Restrict your imports to only the functions and classes that you really need.

    1. Make sure that every of your functions fullfil only **one purpose**.

    1. Try to limit the complexity of your code.
    Install the packages `python3-mccabe` and `python3-flake8` and run:

    $ flake8 --max-complexity 8 my_script.py

    It gives you a list of functions that may be "complex", so it maybe
    a hint to try to make such functions simpler.

    1. Use meaningful names for your function, classes, and variables:

    a. Be as specific as possible.
    b. Use nouns for classes and verbs for methods.
    c. Use only common names for temporary variables like `i`, `j`, `k`,
    `m`, `n` for integers and `c`, `d`, and `e`, for characters.

    1. Write "simple" functions.