コンテンツにスキップ

DevBlueprint

01.ShellScript コーディング規約

01.ShellScript コーディング規約

このドキュメントでは、CI/CDのワークフローや、開発補助のためのスクリプトでBash/Zshなどのシェルスクリプトを記述する際の規約を定めます。シェルスクリプトは、書き方によって挙動が大きく変わるため、安全で予測可能なコードを書くことが重要です。

Note

"共通原則との関係" 本規約は、01.共通コーディング原則を、シェルスクリプトに特化・具体化したものです。必ず共通原則にも目を通してください。

1. 基本方針(Guiding Principles): Google Shell Style Guide準拠

本プロジェクトのシェルスクリプトは、世界的に広く参照されているGoogle Shell Style Guideに準拠することを基本とします。
このガイドは、堅牢で保守性の高いシェルスクリプトを書くための、優れたベストプラクティス集です。

2. 必須の安全設定と作法 (Essential Safety Settings and Best Practices)

2.1. Shebang (シバン)

全てのスクリプトファイルの先頭には、どのシェルで実行すべきかを明記するShebangを必ず記述します。
bashを想定している場合は、環境によるパスの違いを吸収するため、#!/usr/bin/env bashを使用することを推奨します。

2.2. エラー発生時の即時終了 (安全設定)

スクリプトの意図しない動作を防ぐため、ファイルの先頭（Shebangの直後）に、以下の「安全設定」を記述することを強く推奨します。
```
set -euo pipefail
```
- set -e: コマンドがエラー（ゼロ以外の終了コード）になった時点で、スクリプトを即座に終了させます。
- set -u: 未定義の変数を使用しようとした時点で、スクリプトを即座に終了させます。
- set -o pipefail: パイプライン（|）の途中でいずれかのコマンドが失敗した場合、パイプライン全体の終了コードをエラーとします。

3. ツールによる規約の強制 (Tool-Enforced Regulations)

静的解析: ShellCheck
- 役割: シェルスクリプトの一般的なエラー、バグ、アンチパターン、スタイル問題を自動で検出してくれる、非常に強力な静的解析ツールです。
- 運用: VSCodeの拡張機能timonwong.shellcheckを導入し、リアルタイムでコードをチェックします。CI/CDプロセスにshellcheckコマンドを組み込み、警告が出た場合はマージをブロックすることを推奨します。

4. コーディングスタイル (Coding Style)

4.1. 変数

命名: lower_snake_case（小文字のスネークケース）を基本とします。環境変数との衝突を避けるため、ローカル変数を大文字にするのは避けてください。

展開: 変数を展開する際は、意図しない単語分割やグロブ展開を防ぐため、常にダブルクォーテーションで囲みます。

# 良い例
file_name="my report.txt"
echo "$file_name" # -> my report.txt

# 悪い例: myとreport.txtが別々の引数として解釈される
# echo $file_name

4.2. コマンド置換

古いバッククォート (`command`) は使用せず、ネストも可能なモダンな $(command) 形式を必ず使用します。

4.3. 条件分岐

文字列比較やファイルチェックには、古い[（testコマンド）ではなく、より高機能で安全な[[ ... ]]を使用します。
```
# 良い例
if [[ "$my_var" == "hello" && -f "$my_file" ]]; then
    echo "条件に一致しました。"
fi
```

4.4. 関数

functionキーワードは省略し、my_func() { ... }の形式で定義します。
ローカル変数は必ずlocalキーワードで宣言し、グローバルスコープの汚染を防ぎます。
```
# 良い例
my_func() {
  local my_local_var="Hello"
  echo "$my_local_var, $1"
}
```

5. 機能IDとの連携

スクリプト内の特定の処理が、何らかの要求仕様に関連する場合は、コメントで機能IDを明記します。

# DEPLOY-CI-2.1: ビルド成果物をS3にアップロードする
echo "Uploading artifacts to S3..."
aws s3 cp ./site s3://my-bucket/ --recursive