Writing Clean and Pythonic Code

SQI Seminar Series Writing Clean and Pythonic Code

James Mertz (5125 – Software Quality Assurance)

• Started at JPL in 2018 • Software QA Engineer for the Europa Clipper Project • Using Python for ~10 years • Software Test Engineer • JPL side tools • Hobby • GitHub Profiles • JPL: https://github.jpl.nasa.gov/mertz • Public: https://github.com/mertzjames

Python is an interpreted, high-level, general-purpose programming language. Created by Guido van Rossum and first released in 1991, Python's design philosophy emphasizes code readability with its notable use of significant whitespace. Its language constructs and object-oriented approach aim to help programmers write clear, logical code for small and large-scale projects.

New Python developers sometimes struggle with “Pythonic” philosophy of clean, readable code. In this presentation, I will share with you my top techniques to make your Python code cleaner and easier to read.

Guido Van Rossum (Python Creator) “Code is read much more often than it is written.”

File:Guido-portrait-2014-curvves.jpg. (2019, May 24). Wikimedia Commons, the free media repository. Retrieved 17:04, August 13, 2019 from https://commons.wikimedia.org/w/index.php?title=File:Guido-portrait-2014-curvves.jpg&oldid=351725518. © 2019 California Institute of Technology. Government sponsorship acknowledged. jpl.nasa.gov What Does It Mean to be Pythonic? The Zen of Python; import this

Beautiful is better than ugly. Explicit is better than implicit. Simple is better than complex. Complex is better than complicated. Flat is better than nested. Sparse is better than dense. Readability counts. Special cases aren't special enough to break the rules. Although practicality beats purity. Errors should never pass silently. Unless explicitly silenced. In the face of ambiguity, refuse the temptation to guess. There should be one-- and preferably only one --obvious way to do it. Although that way may not be obvious at first unless you're Dutch. Now is better than never. Although never is often better than *right* now. If the implementation is hard to explain, it's a bad idea. If the implementation is easy to explain, it may be a good idea. Namespaces are one honking great idea -- let's do more of those!

1. Use tools to help you. 2. Properly structure your project. 3. Follow a Style Guide. 4. Document all the things!

• Tools such as IDEs, linters, and auto formatting modules can: • Make writing clean code easier • Make writing your code quicker • Make your code easier to test • Make it easier to refactor (change) you code

• black.py – Auto-formatting tool for the PEP 8 Style Guide. (Officially supported and maintained by Python Software Foundation) • PyLint – Linter (checking tool) that includes checking for PEP 8 Style Guide. • PyCharm – Full Python developmental IDE that incorporates the features of black.py and PyLint. (Supported by CAE) • VS Code – Text Editor with a Python extension that incorporates the features of black.py and PyLint. • Sphinx - Documentation site generator.

• Properly structuring your project will: • Make the project easier to navigate and read • Enable you to quickly make changes • Guide your development process

• notebooks/ - The location of all your notebooks project_root/ • data/ - Any data (external, interim, processed, and raw) │ • reports/ - Reports intended for your audience ├── notebooks/ • Cookie Cutter: https://github.jpl.nasa.gov/mertz/project_cookiec ├── data/ utter_notebook • For more complex projects, consider this ├── reports/ “cookie cutter”: https://drivendata.github.io/cookiecutter-data- └── README science/

© 2019 California Institute of Technology. Government sponsorship acknowledged. jpl.nasa.gov 2. Properly Structure Your Project Suggested Project Layout: One off scripts project_root/ • project.py – The main script • tests.py – A script that conducts testing │ of the main script • requirements.txt – A list of any third ├── project.py party packages required to run the script ├── tests.py • README – A brief overview of what your project is, how to use, and how to install ├── requirements.txt • setup.py – A special script used to “install” your script (optional) ├── README • Cookie Cutter: https://github.jpl.nasa.gov/mertz/project_c └── setup.py ookiecutter_script

© 2019 California Institute of Technology. Government sponsorship acknowledged. jpl.nasa.gov 2. Properly Structure Your Project Suggested Project Layout: Installable Packages project_root/ • project/ - The source of your project code • tests/ - A collection of testing scripts that test out │ your source code ├── project/ • docs/ - A collection of documentation for the project (including Tutorials, How-To Guides, References, ├── tests/ and Explanations) ├── docs/ • HOW_TO_CONTRIBUTE – How others from the ├── HOW_TO_CONTRIBUTE team (or public) can help to contribute to the project • examples.py – A small script that shows examples ├── examples.py of how to use your project (optional) • requirements.txt, README, and setup.py are the ├── requirements.txt same as previous slide ├── README • Cookie Cutter: https://github.jpl.nasa.gov/mertz/project_cookiecutt └── setup.py er_package

“Code Quality” by Randall Munroe is licensed under CC BY 2.5

• I recommend starting with PEP 8 • PEP – Python Enhancement Proposal • A collection of suggestions on how to improve Python • PEP 8 is the official style guide for Python • https://www.python.org/dev/peps/pep-0008/ • “A style guide is about consistency. Consistency with this style guide is important. Consistency within a project is more important. Consistency within one module or function is the most important.” • Tools such as PyLint or black and IDEs such as PyCharm or VS Code will automatically check for PEP 8 adherence

• Use 4 spaces per indentation level • Do not use tabs • Mixing tabs and spaces will raise an error in Python 3 • Using tabs instead of spaces may change the way that the Python file is viewed • Most IDEs will insert spaces instead of tabs when using the tab key • PyCharm and VS Code have these as configurable settings

• Keep a consistent max line length • 88 chars is what black auto formats to • No more than 99 chars • No less than 79 chars • Comments and Docstrings should be limited to 72 characters • Use “rulers” in IDEs to place a visual guide • Why? • Terminals • Presentations • Reports • Online

• Try to limit your functions to no more than 2 or 3 arguments • If you must have more, do not exceed your selected line length • Keep arguments lined up and indented to distinguish between arguments listed and start of function code • If calling a function that require multiple arguments that spans multiple lines, add an additional level of identation

There is a clear distinction between arguments It’s not immediately clear where the arguments and other code. Easier to read. end and the function code begins.

• Imports should be at the top of the file • Do NOT import within a function • Imports should be ordered by: 1. Standard Packages 2. Third-Party Packages 3. Local Packages • Do not use the * import • Do not chain package imports

• ”Code tells you how; Comments tell you why.” ~Jeff Atwood • Do you best to use appropriate names for classes, methods, functions, and variables • Comments and Docstrings • Docstrings are special strings to help document modules, classes, methods, and functions. • Project Documentation • Tutorials • How-To Guides • References • Explanations

1. Use tools to help you. 2. Properly structure your project. 3. Follow a Style Guide. 4. Document all the things!

• JPL has a Python Pathway on degreed: https://degreed.com/pathway/359yn6lkpo?path=pyth on#/pathway • This is a collection of reviewed resources for coding in Python. It includes online and instructor led courses, as well as reviewed content curated by other JPL users.

jpl.nasa.gov References

• https://safjan.com/articles/posts/how-to-organize-data-science- project-based-on-jupyter-notebook/ • https://realpython.com/python-application-layouts/ • https://realpython.com/documenting-python-code/ • https://realpython.com/courses/writing-beautiful-python-code- pep-8/ • https://realpython.com/courses/using-list-comprehensions- effectively/ • https://docs.python-guide.org/writing/structure/ • https://google.github.io/styleguide/pyguide.html • https://www.youtube.com/watch?v=wf-BqAjZb8M

• Ctrl+Shift+P • “Preferences: Open Settings (JSON)” • Add or edit the “editor.rulers” setting

• Open Preferences • Editor -> Code Style -> Python • Select ”Wrapping and Braces” • Edit ”Visual Guides” to the rulers you want