Python Coding Standards

wzdushu@gmail.com (wanzi) — Sat, 20 Jan 2018 10:22:42 +0800

Encoding Declaration

Default encoding is not ASCII. You can specify it using:

`1`	`# coding=<encoding name>`

1
2

#!/usr/bin/python
# -*- coding: <encoding name> -*-

1
2

#!/usr/bin/python
# coding: utf-8

Code Layout

Use four spaces for indentation; avoid using tabs, and never mix tabs with spaces.
Limit line length to 79 characters. Use backslashes for line continuation, but prefer parentheses instead.
Leave two blank lines between classes and top-level functions; leave one blank line between methods within a class.
Module structure order: module description and docstring, import statements, global variables, constants, others. Within import, arrange in order: standard library, third-party, local modules. Avoid writing multiple imports on one line.
Add one space on both sides of operators. Omit spaces around assignment operators in default function arguments. Do not add spaces before closing brackets (], }, )).
Comments must be in English, preferably complete sentences. Start with a capital letter, end with a period (or other punctuation), followed by two spaces before the next sentence. For phrases, punctuation may be omitted.
Always write docstrings for public modules, functions, classes, and methods. Non-public ones don’t require docstrings, but comments are acceptable (placed on the line immediately after def).

Naming Conventions

Avoid using single lowercase letter l or uppercase O as they can easily be confused.
Module names should be short and use all lowercase letters, optionally separated by underscores.
Package names should be short and use all lowercase letters without underscores.
Class names use CapWords. Internal classes use _CapWords.
Exception names use CapWords with an Error suffix.
Global variables should ideally be limited to module scope (like static in C). Two ways to achieve this: use __all__ mechanism or prefix with an underscore.
Function names use all lowercase letters, optionally separated by underscores.
Constant names use all uppercase letters, optionally separated by underscores.
Class attributes (methods and variables) use all lowercase letters, optionally separated by underscores.
Class attributes have three scopes: public, non-public, and subclass API—similar to public, private, protected in C++. Prefix non-public attributes with a single underscore.
If a class attribute conflicts with a keyword, append an underscore. Avoid abbreviations or other workarounds.
To prevent naming conflicts with subclasses, prefix certain class attributes with double underscores. For example, in class Foo, define __a; access via Foo._Foo__a to avoid ambiguity. If a subclass also uses Foo, this protection fails.
The first parameter of instance methods must be self. The first parameter of static methods must be cls.

Code Checking Tools

`1`	`pip install flake8`

After installing flake8 successfully, open VSCode, go to File → Preferences → Settings, and add "python.linting.flake8Enabled": true in settings.json.

Auto Formatting Tool

`1`	`pip install yapf`

After installing yapf successfully, open VSCode, go to File → Preferences → Settings, and add "python.formatting.provider": "yapf" in settings.json.

Project Development Notes:

When starting a new project, keep the following in mind:

README.md: Write your project overview, quick start guide, etc. Although distutils requires no extension, GitHub renders .md files directly as HTML.
ChangeLog.txt: Store version change logs with a consistent format. Refer to web.py’s ChangeLog.txt for examples.
LICENSE.txt: Include the license used by your project. Do not create custom licenses.
requirements.txt: List dependencies on separate lines. This allows pip install to automatically install them.
setup.py: Installation script — detailed later.
docs: Store project documentation such as high-level design, detailed design, maintenance documents, and auto-generated pydoc content. Strongly recommend using Markdown format.
src: Place main module code here. Avoid placing module directories directly in the root directory. Module paths can be specified in setup.py.
tests: Store all unit tests and performance test scripts. Test files must start with test_ so that distutils will automatically include them in packaging. Run tests using:
python -m unittest discover -s ./ -p 'test_*.py' -v

References:

https://www.python.org/dev/peps/pep-0008/ https://wiki.woodpecker.org.cn/moin/PythonCodingRule