適用版本：Python 3.12+

0?? 寫在前面

這份指南在 PEP 8 的基礎上，結合 GNU Mailman 團隊的實踐經驗，由編程獅（W3Cschool）針對國內零基礎同學重新翻譯、精簡和本土化，確保你第一次寫 Python 就能寫出“大廠味”代碼。

1?? 導入語句（import）怎么排？

位置：文件最頂部，順序固定，不要亂放！

# 1. 未來語句 / 元數據
from __future__ import annotations


# 2. 標準庫 & 第三方庫（非 from）
import os
import sys


# 3. 項目內部模塊（非 from）
import mailman.config


# 4. 標準庫 & 第三方庫（from）
from datetime import datetime
from typing import List


# 5. 項目內部模塊（from）
from mailman.models.user import User

編程獅小提示：

安裝 pip install flufl.flake8 可自動檢查順序，VSCode 保存即修復。

2?? 一個文件只放一個類？

• 建議：一個 .py 文件只寫一個公共類，文件名保持小寫下劃線（如 email_sender.py）。

• 如果多個類強相關，可以放在同一文件，但務必在頂部寫明：

  __all__ = ["EmailSender", "EmailConfig"]

• 工具推薦：pip install atpublic 一鍵導出公共 API。

3?? 注釋與空行

• 不要右側注釋，閱讀體驗差：
  ? name = "編程獅" # 網站名稱
  ?

  # 網站名稱
  name = "編程獅"

• 空行規(guī)則：
  • 頂級定義（類/函數/全局變量）之間 2 空行
  • 類內方法之間 1 空行
  • 方法與其文檔字符串之間 0 空行

4?? 引號使用口訣

• 短字符串 → 單引號 'w3cschool'
• 帶英文單引號 → 雙引號 "Don't stop"
• 多行文檔 → 三雙引號：

"""編程獅 Python 風格指南
- 簡潔
- 易讀
- 可維護
"""

5?? 文檔字符串（docstring）

• 必須寫：模塊、類、公共函數、公共方法。
• 單行寫法："""返回用戶名稱"""

• 多行寫法（Google 風格）：

  def get_user(uid: int) -> User:
  """根據用戶 ID 獲取用戶對象
  
  
  
  
  Args:
      uid: 用戶唯一標識
  
  
  
  
  Returns:
      User 實例
  
  
  
  
  Raises:
      ValueError: 用戶不存在
  """

• 每行長度 ≤ 78 字符，W3Cschool 在線編輯器自動換行提示。

6?? 序列判空

• 明確寫長度，減少歧義：
  ? if len(users) == 0:
  ? if not users:（除非變量可能為 0、None、[] 等多種假值）

7?? 私有 vs 公有

8?? 一鍵格式化

裝好以下工具，保存文件即自動完成風格檢查：

pip install black isort flake8 flufl.flake8

• black：自動格式化
• isort：自動排序 import
• flake8：靜態(tài)檢查

9?? 完整模板（復制即用）

新建 demo.py：

"""demo.py - 編程獅 Python 風格示例"""

 
from __future__ import annotations

 
import os
from typing import List

 
__all__ = ["greet"]

 

 
def greet(names: List[str]) -> str:
    """拼接歡迎語

 
    Args:
        names: 用戶名列表

 
    Returns:
        歡迎字符串
    """
    if len(names) == 0:
        return "Hello, 編程獅！"
    return "Hello, " + ", ".join(names) + "!"

想要系統(tǒng)學習 Python 請移步《Python零基礎到高薪就業(yè)》