ヘルプターゲットで自己文書化するMakefile

自己文書化するMakefile

利用可能なすべてのターゲットと説明を表示するhelpターゲットにより、Makefileはより使いやすくなります。このパターンは特別なコメントとawkを使用してフォーマットされたヘルプ出力を生成します。

コメント規約

.DEFAULT_GOAL := help

build: ## アプリケーションバイナリをビルド
	go build -o bin/app ./cmd/...

test: ## カバレッジ付きで全テストを実行
	go test -v -cover ./...

lint: ## linterを実行（golangci-lint）
	golangci-lint run ./...

clean: ## ビルド成果物を削除
	rm -rf bin/ coverage.out

docker-build: ## Docker imageをビルド
	docker build -t myapp .

help: ## このヘルプメッセージを表示
	@awk 'BEGIN {FS = ":.*##"; printf "Usage:\n  make \033[36m<target>\033[0m\n\nTargets:\n"} /^[a-zA-Z_-]+:.*?##/ { printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2 }' $(MAKEFILE_LIST)

仕組み

awkコマンドは：

1. フィールドセパレータを:.*##に設定 — コロンと##の間のすべて
2. ターゲット名の後に:そして##コメントがある行にマッチ
3. 各ターゲット名（シアン色）とその説明を出力
4. $(MAKEFILE_LIST)はインクルードされたすべてのMakefileを含む組み込み変数

出力

makeまたはmake helpを実行すると以下が出力されます：

Usage:
  make <target>

Targets:
  build           アプリケーションバイナリをビルド
  test            カバレッジ付きで全テストを実行
  lint            linterを実行（golangci-lint）
  clean           ビルド成果物を削除
  docker-build    Docker imageをビルド
  help            このヘルプメッセージを表示

デフォルトゴールの設定

.DEFAULT_GOAL := help

これによりhelpがデフォルトターゲットになり、引数なしでmakeを実行するとヘルプメッセージが表示されます。

カテゴリ分けされたヘルプ（上級）

build: ## [Build] アプリケーションをビルド
test: ## [Test] ユニットテストを実行
e2e: ## [Test] E2Eテストを実行
lint: ## [Quality] linterを実行

括弧内にカテゴリプレフィックスを追加し、大きなMakefileではawkスクリプトを変更してターゲットをカテゴリごとにグループ化します。