Python 以“優雅”“簡潔”“可讀性強”著稱，而實現這些特性的關鍵之一，便是 良好的代碼規範與清晰的類型註解。 隨着項目規模的擴大、團隊成員的增加，編寫“看得懂、改得動”的 Python 代碼比“能運行的代碼”更重要。

本篇將帶你深入瞭解兩大核心主題： 一是 類型註解（Type Hinting），幫助代碼更明確、更可維護； 二是 代碼規範 PEP 8，讓你的代碼更符合 Python 社區的最佳實踐。

---

一、為什麼需要類型註解

Python 是動態類型語言，變量類型在運行時決定：

a = 10
a = "Hello"

這種靈活性帶來了便利，但在大型項目中也容易出錯。 例如，當函數參數或返回值類型不明確時，維護者可能難以理解函數的行為：

def add(x, y):
    return x + y

add(3, 5) 能執行，但 add("3", "5") 也能運行（執行字符串拼接），這可能不是你期望的結果。

---

二、類型註解基礎語法

Python 3.5 起引入了類型註解（Type Hints），允許為變量、參數、返回值添加類型説明，從而提升可讀性與可維護性。

def add(x: int, y: int) -> int:
    return x + y

這表示：

• x 和 y 應該是整數；
• 函數返回值是整數。

雖然 Python 解釋器不會強制檢查類型，但編輯器（如 VSCode、PyCharm）或靜態檢查工具（如 mypy）可以在編譯前發現類型問題。

---

1. 變量註解

name: str = "Python"
age: int = 25
price: float = 99.9
is_valid: bool = True

類型註解並不改變變量本質，只是附加類型信息。

---

2. 複雜類型註解

Python 的 typing 模塊提供了豐富的類型註解工具：

from typing import List, Tuple, Dict, Optional

• List：列表類型

  numbers: List[int] = [1, 2, 3]
  

• Tuple：元組類型

  point: Tuple[int, int] = (10, 20)
  

• Dict：字典類型

  user: Dict[str, int] = {"age": 18}
  

• Optional：可為空類型

  name: Optional[str] = None
  

---

3. 函數類型註解實例

from typing import List

def average(scores: List[int]) -> float:
    return sum(scores) / len(scores)

更復雜的示例：

from typing import Dict, List, Union

def process_data(data: Dict[str, Union[int, List[int]]]) -> None:
    print("處理數據：", data)

---

4. 類與方法中的類型註解

在面向對象編程中，類型註解同樣適用：

class User:
    def __init__(self, name: str, age: int):
        self.name = name
        self.age = age

    def greet(self) -> str:
        return f"你好，我是 {self.name}，今年 {self.age} 歲"

---

5. 類型檢查工具：mypy

安裝 mypy：

pip install mypy

檢查代碼類型：

mypy example.py

示例：

def greet(name: str) -> str:
    return 123  # 錯誤：返回類型不匹配

運行 mypy 會提示：

error: Incompatible return value type (got "int", expected "str")

通過這種方式，你能提前發現潛在錯誤，提升代碼質量。

---

三、PEP 8 —— Python 官方代碼風格指南

PEP 8（Python Enhancement Proposal 8）是官方推薦的代碼風格標準，它定義了 Python 編碼的統一規範，讓團隊協作更高效、代碼更易讀。

---

1. 命名規範

類型	示例	説明
模塊名	math_utils	全小寫，使用下劃線分隔
類名	UserProfile	使用大駝峯命名（PascalCase）
函數名	get_user_info	全小寫，使用下劃線分隔
變量名	total_count	簡短有意義
常量名	MAX_RETRY	全大寫

---

2. 縮進與空格

• 每層縮進使用 4 個空格；
• 操作符兩邊留一個空格；
• 逗號後留一個空格。

示例：

def add(a, b):
    return a + b

if a == b:
    print("相等")

不要這樣寫：

if a==b:print("相等")

---

3. 空行與函數佈局

• 頂層函數與類之間空兩行；
• 類內方法之間空一行；
• 合理使用空行提高可讀性。

---

4. 導入規範

• 導入順序：標準庫 → 第三方庫 → 本地模塊；
• 每個導入佔一行。

示例：

import os
import sys

import requests

from myproject.utils import helper

---

5. 行寬與註釋

• 每行不超過 79 個字符；
• 註釋要簡潔、準確；
• 文檔字符串（docstring）使用三引號 """。

示例：

def greet(name: str) -> str:
    """返回一個簡單的問候語"""
    return f"你好，{name}"

---

四、使用自動化工具提升代碼規範

可以使用以下工具來自動檢查或修復代碼風格：

• flake8：檢測代碼是否符合 PEP 8

  pip install flake8
  flake8 your_code.py
  

• black：自動格式化代碼

  pip install black
  black your_code.py
  

• isort：自動排序 import 語句

  pip install isort
  isort your_code.py
  

這些工具配合類型檢查（mypy）使用，可以讓你的代碼始終保持整潔、專業。

---

五、總結

類型註解與 PEP 8 是寫出高質量 Python 代碼的重要基石。 它們不僅讓代碼更規範、更具可讀性，也為大型項目的協作與維護提供了堅實保障。

核心要點回顧：

內容	説明
類型註解	明確變量、函數的類型，提高可讀性與安全性
typing 模塊	提供 List、Dict、Tuple、Union、Optional 等工具
mypy	靜態類型檢查器，提前發現潛在錯誤
PEP 8	Python 官方編碼規範，提升代碼整潔度
flake8 / black / isort	自動化工具，讓規範落地

---