Python 檔案標頭

Python 檔案標頭是放在原始碼檔案開頭的選用文件。專案可以採用共用格式，說明腳本的用途、使用方式、需求與授權；Python 本身並未要求使用特定標頭。只保留能幫助讀者理解或執行檔案的資訊，並遵循專案慣例。

為什麼要在 Python 中採用一致的標頭格式

一致的標頭能在讀者閱讀實作之前，先提供實用背景資訊。標頭可以說明腳本的用途、維護者、執行方式，以及重要的執行環境或相依套件需求。如果授權聲明符合專案實際採用的授權，也能藉此說明程式碼的使用方式。

標頭格式是團隊慣例，不是 Python 語言功能。一次性的小型腳本可能只需要簡短的模組說明；要發布的命令列工具則可能適合附上使用方式與相依套件資訊。多個檔案共用同一個儲存庫時，一致的格式便於檢視；但加入不適用的欄位會讓內容雜亂，也可能留下過時資訊。

Python 檔案標頭的組成

根據檔案的執行與維護方式選擇標頭內容。常見標頭會結合直譯器資訊、模組文件字串，以及提供給讀者的註解。

Shebang 行

shebang 行是放在第一行的標記，例如 #!/usr/bin/env python3。在支援這種標記的系統上，透過檔案路徑執行可執行腳本時，會使用 env 選擇的直譯器。它適合 Unix 類系統上的命令列腳本；如果透過 python script.py 這類命令啟動檔案，就不需要這一行。shebang 行不會安裝 Python，也不會為所有啟動方式選定執行環境。

編碼宣告

Python 3 原始碼預設使用 UTF-8，因此通常不需要編碼宣告。如果原始碼為了配合特定工具或環境而使用其他編碼，Python 會辨識放在第一或第二行的宣告，例如 # -*- coding: latin-1 -*-。宣告必須符合檔案實際使用的編碼；它不是能讓任意文字都變得可讀的通用標記。

模組文件字串與註解

模組文件字串是模組開頭的字串常值，位置在 shebang 行或編碼註解之後。它用來描述模組，並可透過 __doc__ 取得。可用它簡短說明用途及有用的模組層級背景資訊。一般註解則可記載維護者、使用方式、相依套件、版本或授權資訊；Python 不會自動將這些註解解讀為中繼資料。

匯入語句應放在模組文件字串之後，並置於模組其餘可執行敘述之前。需要匯入時，常見慣例是先列出標準函式庫，再列出第三方套件，最後列出專案本身的模組，並在各組之間空一行。

如果腳本的執行方式、所需套件或最低 Python 版本等資訊確實重要，可以在標頭中說明。請讓需求資訊與專案目前的設定一致。只有在授權聲明符合程式碼所採用的授權時才加入，並避免記錄容易過時的個人日期或修改歷程。

Python 檔案標頭範例

這個獨立腳本示範如何以簡潔標頭搭配 shebang 行、模組文件字串，以及供維護者替換為專案專屬資訊的註解。說明文字與註解屬於文件；函式及主程式判斷則是可執行的 Python 程式碼。

#!/usr/bin/env python3
"""Print a short status message for a sample command-line tool."""

# Maintainer: Replace with a team or owner.
# Usage: python status_report.py
# License: Replace with the project's actual license.

def main():
    print("Report ready")


if __name__ == "__main__":
    main()

請依檔案用途調整註解：只有在相依套件或 Python 版本資訊會影響設定或使用方式時，才加入相關說明。範例沒有外部相依套件，因此不需要列出匯入項目。在支援 shebang 行的系統上，將檔案作為可執行程式啟動時，這一行才會發揮作用；若使用 python status_report.py 執行，則會採用該命令指定的直譯器。

Python 檔案標頭的最佳實務

• 標頭應簡短，聚焦於能幫助讀者使用或維護檔案的資訊。
• 遵循專案現有格式，讓相關檔案更容易瀏覽。
• 將模組文件字串放在匯入語句之前；不屬於模組文件字串的備註則使用註解記錄。
• 加入直譯器、相依套件與授權資訊前，先對照專案目前的設定確認內容。
• 資訊不再準確時就更新或刪除；如果專案已在其他地方追蹤作者或修改日期等欄位，就不要重複記錄。

實用的共用標頭，應以能提供下一位開發者所需背景資訊的最精簡形式為準。把標頭視為持續維護的文件，並依專案慣例決定每個檔案需要哪些選用資訊。