python-coding

Core Principles

• Correctness First: Ensure the code runs correctly before optimizing
• Explicit Over Clever: Readability takes precedence over tricks
• Consistency: When conflicting with existing project style, prioritize matching the project style

Quick Reference

Naming Conventions

snake_case

calculate_total

CapWords

UserAccount

UPPER_SNAKE_CASE

MAX_RETRY_COUNT

_leading_underscore

_internal_id

is_

has_

can_

is_active

has_permission

Type Annotations

# Use modern syntax (Python 3.10+)
def process(items: list[str]) -> dict[str, int]: ...
def get_user(id: int) -> User | None: ...

# Use Protocol for structural typing
from typing import Protocol

class Drawable(Protocol):
    def draw(self) -> None: ...

Function Design

• Single Responsibility: Each function does one thing
• Length Limit: ≤60 lines (ideally ≤20 lines)
• Parameter Count: ≤5 parameters (use dataclass if exceeding)
• Parameter Order: Required → Optional → *args → **kwargs

# Use dataclass when there are too many parameters
@dataclass
class EmailConfig:
    to: str
    subject: str
    body: str
    cc: list[str] = field(default_factory=list)

def send_email(config: EmailConfig) -> None: ...

Import Rules

# Group order, sorted alphabetically within each group
import os
import sys
from pathlib import Path

import requests
from dotenv import load_dotenv

from myapp.models import User
from myapp.utils import logger

• Prohibit

  from module import *

• No I/O or recalculation during import phase

Error Handling

# Use specific exception types
try:
    result = data["key"]
except KeyError:
    result = default_value
except requests.Timeout:
    logger.warning("Request timed out")
    raise

# Prohibit bare except
# Bad: except Exception: pass

Docstring Rules

Use Chinese docstrings (Google Style)

def load_config(path: Path) -> dict[str, Any]:
    """加载并校验配置文件.

    该函数读取配置文件并返回解析结果, 不修改全局状态.

    Args:
        path: 配置文件路径.

    Returns:
        解析后的配置字典.

    Raises:
        ValueError: 当配置不合法时抛出.
    """

• Use Chinese descriptions
• Use English keywords (Args/Returns/Raises)
• Use English half-width punctuation (

  . , :

  )
• Describe semantics/constraints/side effects, not implementation details

Comment Rules

• Write in Chinese
• Only use English half-width punctuation (

  . , ;

  )
• Add space between Chinese and English:

  使用 LRU 缓存

• Explain why, not what the code does

# 使用贪心策略, 因为回溯会导致指数级复杂度
result = greedy_search(data)

Code Formatting

• Use 4 spaces for indentation (disable tabs)
• Line width ≤120 characters
• Use

  ()

  for line breaks, avoid

  \

• 2 blank lines between top-level definitions, 1 blank line between methods in a class

Self-Check List

• Import groups are correct (standard library/third-party/local)
• All public APIs have type annotations
• All public APIs have docstrings
• No duplicate types (if the signature already has the type, do not repeat it in the docstring)
• Comment punctuation is English half-width
• No bare

  except Exception: pass

• Functions ≤60 lines, parameters ≤5
• No magic numbers (use named constants)
• Use context manager to manage resources
• Style conforms to project conventions

Detailed Resources

• Detailed Style Guide - Complete code examples and in-depth explanations
• Design Patterns Reference - Factory, Strategy, Observer 等
• Refactoring Patterns Reference - 常见代码异味及重构方法