透過 pre-commit 來提升程式碼品質與統一專案風格

什麼是 pre-commit hooks ?
安裝 pre-commit
風格統整
推薦配置

在軟體開發中，少不了團隊合作的環節，而多人同時開發的情況下，維持程式碼的一致性和風格顯得格外重要。

一致性可以為專案品質打下良好的基礎，除了提升程式碼的可讀性，有了明確的指引可供遵循後，也能減少團隊成員之間的摩擦。

pre-commit 是一個方便的工具，能幫助我們在提交代碼前自動檢查和修正程式碼風格問題。本文將介紹如何使用 pre-commit hooks 來統一專案風格。

什麼是 pre-commit hooks ?

pre-commit hooks 是 Git 提供的一種機制，它允許在執行 git commit 前運行自定義的腳本。這些腳本可以用來檢查代碼是否符合團隊的標準，例如程式碼格式、語法檢查、測試情況等等。

pre-commit 是一個管理這些 hooks 的工具，支持多種語言和格式化工具，並且可以輕鬆整合到現有工作流程中。

使用 pre-commit 的好處包括：

自動化程式碼檢查：在 push code 前自動檢查程式碼風格、語法錯誤等。
統一程式碼風格：通過工具自動修正，使得所有人產出的程式碼風格一致。
提升程式碼品質：減少低級錯誤(引用不必要的套件、創建無需使用的變數)和 code review 的工作量。

安裝 pre-commit

安裝 pre-commit 很簡單，直接用 pip

pip install pre-commit

安裝完成後，直接在專案根目錄中安裝 pre-commit

pre-commit install

執行後，專案會新增一個名為 .pre-commit-config.yaml 的檔案，用於配置各種 pre-commit hooks。建議將這個檔案加入專案中，讓團隊都使用相同的配置。

當完成安裝後，在執行 git commit 時，將會根據配置檢查程式碼，會出現類似下方的檢查畫面

風格統整

為了統一專案的代碼風格，可以在 .pre-commit-config.yaml 中配置多種工具。

例如，可以使用 black 來格式化 Python 代碼，用 flake8 來檢查語法錯誤，用 isort 來排序 import 語句。以下是一些常用的配置：

repos:
  - repo: https://github.com/psf/black
    rev: 23.9.1
    hooks:
      - id: black
  - repo: https://github.com/PyCQA/flake8
    rev: 6.1.0
    hooks:
      - id: flake8
  - repo: https://github.com/PyCQA/isort
    rev: 5.12.0
    hooks:
      - id: isort

增加配置後，除了 commit 之外，也可以使用以下指令來檢查整個專案

pre-commit run --all-files

執行指令後，會自動檢查並修正能夠修正的問題，有些例如引用套件未使用的狀況，則需要手動移除，以下範例中的 requests 套件被 import 但從未使用，此時檢查結果會報錯，需要手動刪除。

import requests # <-- imported but not used


print('hello pre-commit')

推薦配置

下面提供常用的配置供參考， black 作為管理程式碼風格，flake8 進行檢查，isort 用來排序 import 的套件。

除此之外，還有一些實用的 hooks，例如去除行尾空白、檢查檔案結尾、檢查 YAML 語法，還有一個我個人特別喜歡的把引號處理，把允許改變的 " 統一改為 ' ，很方便。

repos:
  - repo: https://github.com/psf/black
    rev: 23.9.1
    hooks:
      - id: black
        args: [--line-length=88]
  - repo: https://github.com/PyCQA/flake8
    rev: 6.1.0
    hooks:
      - id: flake8
        args: [--max-line-length=88, --ignore=E203,W503]
  - repo: https://github.com/PyCQA/isort
    rev: 5.12.0
    hooks:
      - id: isort
        args: [--profile=black]
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.4.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: double-quote-string-fixer

透過這些簡單的配置，pre-commit 可以幫助在 push code 之前自動檢查和修正，確保開發團隊所有成員的產出風格一致，從而提高開發效率和品質。

在加入 pre-commit 後，每當執行 git commit 時，便會進行一輪檢查，如果沒修好就沒辦法成功 commit ，當然有時候也會有人偷偷繞過啦，只要加個 --no-verify 就可以跳過檢查了。

git commit -m "feat: I am a bad boy" --no-verify

Updated: 2024/09/07