適用版本：Python 3.12+

0?? 寫在前面

這份指南在 PEP 8 的基礎(chǔ)上，結(jié)合 GNU Mailman 團(tuán)隊(duì)的實(shí)踐經(jīng)驗(yàn)，由編程獅（W3Cschool）針對(duì)國內(nèi)零基礎(chǔ)同學(xué)重新翻譯、精簡和本土化，確保你第一次寫 Python 就能寫出“大廠味”代碼。

1?? 導(dǎo)入語句（import）怎么排？

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

# 1. 未來語句 / 元數(shù)據(jù)
from __future__ import annotations


# 2. 標(biāo)準(zhǔn)庫 & 第三方庫（非 from）
import os
import sys


# 3. 項(xiàng)目內(nèi)部模塊（非 from）
import mailman.config


# 4. 標(biāo)準(zhǔn)庫 & 第三方庫（from）
from datetime import datetime
from typing import List


# 5. 項(xiàng)目內(nèi)部模塊（from）
from mailman.models.user import User

編程獅小提示：

安裝 pip install flufl.flake8 可自動(dòng)檢查順序，VSCode 保存即修復(fù)。

2?? 一個(gè)文件只放一個(gè)類？

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

• 如果多個(gè)類強(qiáng)相關(guān)，可以放在同一文件，但務(wù)必在頂部寫明：

  __all__ = ["EmailSender", "EmailConfig"]

• 工具推薦：pip install atpublic 一鍵導(dǎo)出公共 API。

3?? 注釋與空行

• 不要右側(cè)注釋，閱讀體驗(yàn)差：
  ? name = "編程獅" # 網(wǎng)站名稱
  ?

  # 網(wǎng)站名稱
  name = "編程獅"

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

4?? 引號(hào)使用口訣

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

"""編程獅 Python 風(fēng)格指南
- 簡潔
- 易讀
- 可維護(hù)
"""

5?? 文檔字符串（docstring）

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

• 多行寫法（Google 風(fēng)格）：

  def get_user(uid: int) -> User:
  """根據(jù)用戶 ID 獲取用戶對(duì)象
  
  
  
  
  Args:
      uid: 用戶唯一標(biāo)識(shí)
  
  
  
  
  Returns:
      User 實(shí)例
  
  
  
  
  Raises:
      ValueError: 用戶不存在
  """

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

6?? 序列判空

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

7?? 私有 vs 公有

8?? 一鍵格式化

裝好以下工具，保存文件即自動(dòng)完成風(fēng)格檢查：

pip install black isort flake8 flufl.flake8

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

9?? 完整模板（復(fù)制即用）

新建 demo.py：

"""demo.py - 編程獅 Python 風(fēng)格示例"""

 
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)學(xué)習(xí) Python 請(qǐng)移步《Python零基礎(chǔ)到高薪就業(yè)》