Style

Overview

Web developers have lots of decisions to make, everything from code formatting to API design to feature scope.

This document attempts to set conventions (sometimes arbitrary) to make code more readable, by way of consistency. This also includes development best practices and high-level design that you will encounter repeatedly.

Python style

Python 3

We use Python 3, exclusively.

No new projects should be started in Python 2. Major library support for Python 3 is nearly universal.

Python 2 will reach end-of-life in 2020: no new features, no bugfixes, and no security fixes. Python 2 code should be migrated, using tools such as 2to3, six or python-future. Porting guides can be found here or on the official Python documentation.

Basics

• Use four spaces for indentation. No tabs.
• Use snake_case for variable (value-level) names, CamelCase for class (type-level) names, and SCREAMING_SNAKE_CASE for constants. Avoid _leading_underscore names.
• Limit lines to 80 characters (preferably), or 100 characters (almost always). Exceptions are allowed.
• Make public names descriptive of the use, not the implementation.
• Files should be in UTF-8 text encoding.

Style checkers

There are many Python style checkers you can use while coding (aka passive-aggressive):

• pycodestyle (formerly pep8): checks against standard Python style PEP8.
• pydocstyle: checks doc comments against standard Python style PEP257.
• pylint: fancier style checking
• flake8: combines pycodestyle and pyflake to check for actual errors
• bandit: checks for security issues

Some of these will auto-format your code (aka aggressive):

• autopep8: automatically reformats to pycodestyle (pep8) styles

If you would like to enforce code style on every commit (recommended), there is a pre-commit config (.pre-commit-config.yaml) setup in the repo. If you install pre-commit in your git repo, this will run a series of style checkers and force you to fix your style before it will allow you to commit.

Separate app or add into hknweb?

Model design

View design

URL design

Template design