2.6 KiB
2.6 KiB
指令檔開頭「用途／更新時間」標頭範本
本範本定義 doc-funcs 第 3-2 步指令檔草稿開頭必備的註解區塊格式。「用途」與「更新時間」必須包在同一個註解區塊內，不得拆成兩個分開的區塊；此標頭屬於檔案說明標頭（含外框分隔線），實作與後續輸出訊息格式正規化時必須原樣保留，不得移除或轉成 階段 前綴。
佔位符
-
{用途說明}：一到三行，說明這份指令檔做什麼、在什麼情境被呼叫、重要副作用；多行時每行開頭都要有註解符號。 -
{更新時間}：台灣時區（Asia/Taipei），固定格式yyyy/MM/dd HH:mm:ss，可用下列指令取得：TZ='Asia/Taipei' date +'%Y/%m/%d %H:%M:%S'
變體 A：# 註解（*.sh、*.bash、*.ps1、Makefile、yaml、Dockerfile、docker-compose）
# ============================================================================
# 用途：{用途說明}
# 更新時間：{更新時間}
# ============================================================================
填入後範例：
#!/usr/bin/env bash
# ============================================================================
# 用途：打包 Web 專案並上傳部署壓縮檔至部署主機，供 CI 部署階段呼叫。
# 更新時間：2026/07/15 14:30:00
# ============================================================================
變體 B：:: 註解（*.bat、*.cmd）
:: ===========================================================================
:: 用途：{用途說明}
:: 更新時間：{更新時間}
:: ===========================================================================
填入後範例：
@echo off
:: ===========================================================================
:: 用途：清理建置輸出目錄並重新建置方案，供本機開發快速重建使用。
:: 更新時間：2026/07/15 14:30:00
:: ===========================================================================
（改用 REM 亦可，但同一份檔案內擇一使用並保持一致。）
放置規則
- 標頭放在檔案最前面；若第一行是必須位於首行的宣告（例如 shebang
#!...、@echo off），標頭緊接在其後。 - yaml 檔若有 document marker（
---），#標頭放在---之前即可。 - 外框分隔線長度不強制，但上下外框必須成對出現，且整個標頭（含外框）視為同一個註解區塊。
- 「用途」與「更新時間」兩行的中文標籤與順序依本範本，不得只留其中一項。