Encoding Declaration

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

1

# coding=<encoding name>

or

1
2

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

or

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