Good coding practices

Whether you are working alone or working in a team, one of the most valuable things you should keep in mind is context transfer. It is not enough to just track the changes made to the code, but to also track why those changes were made. Many of the best practices covered within this lecture will be various flavors of recoding this kind of context in a way that is clear to other developers, or even to yourself when you look back at old code.

When context is well recorded it becomes easier for other develops to be on-boarded into your codebase, structural changes to the code become easier to manage, and overall it leads to code that is easier to maintain in the long run.

Context transfer

Ways to boost context transfer:

  • Pair programming: Work with another developer in real time when writing your code. Typically you have one person drive the keyboard focusing on code syntax and code legibility while the other drives the code structure focusing on how the code should be organized and the algorithms being used. It is typically useful to switch these roles every so often.

  • Git commit messages: Include the why for every change directly in the commit message

  • GitHub Pull Requests: Use this space for the larger reason behind any changes and/or features

  • Architecture Decision Record (ADR): For larger code bases ADRs can be used to track changes to a code’s architecture over time. These records are kept in the repository next to the code and can be refereed to by any developer who wants to know why the code is structured the way it is.

Text editors

For most everyday use you will likely be writing code in a text editor and running your programs via the command line. It can be useful to have a good text editor that supports syntax highlighting, live linting (syntax and style checking), and is easy to configure the way you want. I can highly recommend VScode as a free text editor with all the features above.

For python coding in VScode you will want to install the Python extension by Microsoft (you will be prompted to install it when you first open a .py file) and the Jupyter extension by Microsoft (other extensions are available if you are coding in another language). Other useful extensions are the Excel Viewer extension for easier viewing of CSV files, open in browser for and option to open HTML files in your browser, MyST-Markdown for rendering markdown files, and Code Spell Checker for basic spell checking.

Note

The most important part for a text editor is that you are comfortable using it. Feel free to try out different ones to find what works best for you.

Programming fonts

In addition to a good text editor you will also want a good monospace font. I can recommend FiraCode. This font has ligatures (special characters used to “connect” specific letters that appear next to each other) that help when reading code (e.g. turing >= int a “less-than or equal” to sign).

Note

Use this font in VScode you will want to install the Disable Ligatures extension to allow the ligatures to be turned off on the line you are currently typing and set the following options in VScode’s settings.json file:

{
    "editor.fontFamily": "Fira Code",
    "editor.fontLigatures": true,
    "editor.fontWeight": "500",
    "disableLigatures.mode": "Line",
}

All other font options (such as font size) can be set from the normal settings panel.

Coding style and linting

What is a coding style? Beyond the syntax of a coding language, a coding style is a set of conventions that can be followed to make it easier for other developers (including your future self) to read you code and to understand the intention behind your code. For python coding PEP 8 is used as the base for most styles.

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.

However, know when to be inconsistent – sometimes style guide recommendations just aren’t applicable. When in doubt, use your best judgment. Look at other examples and decide what looks best. And don’t hesitate to ask!

Here are some examples of PEP 8 conventions:

  • Use 4 spaces to indent lines (rather than a tab)

  • A max line limit of 79 characters (preferred by people who use command line editors, I typically override this to be higher)

  • Constants are defined at the module level with names in ALL_CAPS

  • Class names should normally use the CapWords convention

  • Function names should be lowercase, with words separated by underscores as necessary to improve readability

While you could read over PEP 8 and try to memorize it, the most effective way to lean (and stick to) PEP 8 standards is to use a linter for you code. A linter is a package that will automatically check your code style through a command line function. Some text editors support live linting to check your code style as you type your code (similar to a spell checker).

The two most common linters used for python are pylint and flake8. While both cover the standard PEP 8 rules, they each have a different set of additional style rules that are checked (i.e. checking for things like unused imports). Of the two flake8 is less opinionated making it a bit easier to get on with when first learning to stick to a style, because of this we will be using it for this lecture. Once flake8 is install you can run it on the command line with:

flake8

Note

To set up VScode to use flake8 open the settings, search for python linting, enable flake8, disable pylint, and enable “lint on save” (linting as you type is a bit buggy for python in VScode).

Configuring your linter

While flake8 is a great starting point, it is just that, a starting point. PEP 8 should be used as a guideline for your projects style and if there are any rules you don’t agree with you are free to turn them off. While this can be configured globally on your local computer, I would recommend doing at the project level inside your code’s .flake8 file. By doing it at the project level your choice of style rules will be saved inside the project for all developers to see and use.

In particular, the flake8 rules W503 and W504 are the exact opposite of each other, so one of them must be ignored. Within this project I have already set up the flake8 configuration in the .flake8 file so it will:

  • ignore the project configuration folders (.git, docs, etc…)

  • Set the max line length to 120

  • Turn off rule W503

  • Turn off BLK100 (flake-black is an optional set of rules we are not going to be using)