Skip to content

Data Science › Python Foundations › 軟體工程實務

軟體工程實務 (Software Engineering for Data Work) ​

讓程式在幾個月後、或交給別人時仍然可讀、可改、可重跑。對分析工作而言,目標是可讀性、可維護性、可測試性、可重現性。

從 notebook 到可維護程式 ​

text
探索 (notebook) → 抽出函式 → 搬進模組 (src/) → 加測試 → 加 CLI 入口 → 固定環境
訊號該做的事
同一段 cell 複製到第二個 notebook抽成函式,放進 src/ 模組 import
notebook 要「從頭依序執行」才會對改成腳本,或至少 Restart & Run All 確認
參數寫死在程式中(路徑、門檻)移到 CLI 參數或設定檔,見 腳本與 CLI
換台電腦就跑不動用 pyproject.toml + lock 檔固定環境,見 Python 套件與環境

建議的專案結構:

text
project/
├── pyproject.toml        # 依賴與工具設定
├── uv.lock               # 鎖定的確切版本
├── src/mypkg/            # 可重用的函式
├── scripts/              # 入口腳本(呼叫 src 的函式)
├── notebooks/            # 探索與圖表,import src 的函式
├── tests/
├── data/raw/             # 原始資料:唯讀,不進 git
└── results/              # 產出:可由程式完整重建

原始資料永遠不覆寫;所有中間檔與結果都應能由程式從 data/raw/ 重建。大型資料與模型版本控管見 DVC,流程化見 工作流引擎。

風格:PEP 8 與自動化工具 ​

PEP 8 是共同的閱讀基準,交給工具處理,不要在 review 時靠人眼檢查。

工具作用指令
ruff checklinter:未使用的 import、未定義變數、常見 bug、PEP 8uv run ruff check --fix .
ruff formatformatter(相容 black)uv run ruff format .
mypy / pyright依型別註記做靜態檢查uv run mypy src
pre-commitcommit 前自動跑上述工具pre-commit install

ruff 一個工具取代了 flake8、isort、pycodestyle、black,速度也快得多。

toml
# pyproject.toml
[tool.ruff]
line-length = 100

[tool.ruff.lint]
select = ["E", "F", "I", "B", "UP"]   # pycodestyle、pyflakes、import 排序、bugbear、pyupgrade

命名 ​

對象慣例例子
變數、函式snake_case,函式用動詞raw_counts、calculate_tpm()
類別CamelCaseSampleSheet
常數UPPER_SNAKEMIN_READ_LENGTH = 30
內部使用前綴 __parse_header()
布林is_ / has_is_paired_end
差好
x、data2、tmp_final、df_new_newraw_counts、filtered_counts、counts_cpm
do_stuff()filter_low_expression()
thrmin_counts_per_sample

判斷標準:兩天後只看名字還想得起它的角色嗎?

註解與 docstring ​

註解解釋為什麼,程式碼本身說明做什麼。

python
x = x + 1  # Increment x                    ← 差:重念程式

# The API returns duplicated rows for retried events, so dedupe by event_id first.
df = df.drop_duplicates("event_id")         # ← 好:說明外部限制

公開函式寫 docstring:做什麼、輸入輸出、前提與副作用。常見格式為 Google style 或 NumPy style(科學套件慣用):

python
def scale(values: np.ndarray) -> np.ndarray:
    """Scale values to the [0, 1] range.

    Parameters
    ----------
    values : np.ndarray
        Numeric array with at least one finite value.

    Returns
    -------
    np.ndarray
        Array of the same shape; NaN stays NaN.
    """

函式與重構 ​

重構訊號處理
函式同時讀檔、轉換、畫圖、寫檔拆開:讀取 / 純轉換 / 輸出各自一個函式,純轉換最容易測試
同一規則出現在兩三處抽成函式(DRY),否則改規則時只會改到一處
函式超過一個螢幕、巢狀超過 3 層拆小、提早 return
改一個地方牽動很多處邊界不清楚,重新切分模組

DRY (don't repeat yourself) 是避免邏輯重複,不是零重複。只出現兩次、且未來可能分開演變的程式,先別抽象;過早抽象只是把簡單的問題藏起來。

class 只在有狀態、資料與行為強關聯時才用;只是一組函式就放模組。設計細節見 類別。

可重現性 (Reproducibility) ​

面向做法
環境pyproject.toml + uv.lock;記錄 Python 版本(.python-version)
亂數rng = np.random.default_rng(seed) 傳入函式;ML 另外固定框架 seed
參數寫在設定檔或 CLI 參數,跟結果一起存檔
資料原始資料唯讀;記錄來源版本(參考基因組版本、資料庫釋出日期)
執行紀錄用 logging 記錄參數、版本、輸入檔,見 腳本與 CLI
程式版本git commit;結果檔名或 metadata 帶 commit hash
python
import numpy as np

def subsample(x, n, rng: np.random.Generator):
    return rng.choice(x, size=n, replace=False)

rng = np.random.default_rng(20240315)       # 新 API;不要用全域的 np.random.seed()
subsample(np.arange(100), 5, rng)

測試保護重構 ​

有測試才敢改。至少替最重要的轉換函式寫幾個單元測試,見 測試。

提交前檢查 ​

問題
命名能獨立傳達角色嗎?
有重複邏輯值得抽出嗎?
註解在解釋「為什麼」嗎?公開函式有 docstring 嗎?
ruff check / ruff format 乾淨嗎?
測試通過嗎?這次改動有沒有測試保護?
結果能從原始資料重建嗎?