シェルスクリプトの設計書とは？必要な項目や書き方等を解説！

一般的にシェルスクリプトの大半は、運用ツールとしての処理が主な用途となります。大抵の処理は「起動・停止・状態表示」や「リソースチェック」「夜間バッチ処理」等の単発処理となるため、設計書と言う観点ではかなり軽視されがちです。

シェルスクリプトはOSの組み込みコマンドを駆使することで、非常に有用なツールとなります。一言で表すならば「かゆいところに手が届く」ため、運用上欠かすことは出来ません。

ところが、私の経験的に7割近くのプロジェクトが、「運用ツール（シェルスクリプト）」設計書のメンテナンスが出来ていません。出来ていないどころか、シェルスクリプトの一番上にコメントで用途を記述して終わらせている場合が実に多い・・

極めつけが、シェルスクリプト名に「db0001.sh」など、番号で付与されている場合、ファイルを開いて中身を確認する以外に用途が全く推測できず、障害対応以前にシェルスクリプトの解析から入ることになってしまいます。

この記事では、シェルスクリプトの設計書について、必要な項目や書き方等を解説します。

シェルスクリプト設計書とは

シェルスクリプト設計書は、主に2つの役割があります。

なお、シェルスクリプト設計書に、統一された書式や形式はありません。

シェルの設計に必要な項目

標準規約

「ディレクトリ構成」や「スクリプト命名規約」「コーディング規約」等、複数のエンジニアが参画するプロジェクトにおいて、一定の品質を担保するために定める標準規約を作成します。標準規約は、スクリプト毎に作成するものではなく、プロジェクト単位で作成されます。

ディレクトリ構成

ディレクトリ構成とは、運用ツール開発において、予め用途ごとにファイルシステム内に作成するディレクトリを決定することを指します。

ディレクトリ構成は、一旦プロジェクトへリリースしてしまうと、おいそれとは変更できません。後々になって変更すると、ソース内部のパス等がズレてしまうため、システム自体が正常に動作しなくなってしまう可能性があります。予めきっちりと構成を決定しておくことが重要です。

スクリプト命名規約

命名規約とは、プログラミングを行う際にソースコード上の識別子の名称となる文字列や、ソースファイル自体の名前を決定するためのルールを定めたものを指します。

スクリプト名及び、関数に関する命名規約（例

先頭ワードは、目的を表す単語から始まり、後に対象や用途をキャメルケースにて記述する。

目的を表す単語の例

ワード	意味	記述例
is	有効・無効を表わすもの	isProcAlive、isPortAlive
get	情報やモノ取得を表すもの	getName、getTarget
exec	実行を表すもの	execBackup、execSnap
mk	作成を表すもの	mkDir
rm	除去を表すもの	rmDir

コーディングフェーズ前までにワードをすべて出し切るかは、プロジェクトによりマチマチです。多くのプロジェクトでは、それまでに蓄積された既存資産があるはずなので、流用することが一般的です。

変数に関する命名規約（例

すべての変数は、スネークケースを使用する。

• 定数及びグローバル変数
  定数及び、グローバル変数はすべて大文字にて記述する。
  例）SCRIPT_NAME、BASE_DIR
• ローカル変数
  例）proc_cnt、file_name

コーディング規約

コーディング規約とは、ソフトウエア開発において、プログラムコーディングにおける統一的なガイドラインを指します。「可読性」や「保守性」を高めるメリットがあります。

コーディングエリア（例

ソースコードは、下記の指定された領域へ、それぞれ用途ごとに正しく記述すること。

• シェバン
• プログラム概要
  • バージョン、作成日、仕様方法、説明、設計書の所在
• 変数の宣言領域
• 関数を記述する領域
• 事前処理ロジックを記述する領域
• メイン処理ロジックを記述する領域
• 事後処理ロジックを記述する領域

制御文「if」（例

制御文で使用する「test」コマンドについては、可読性の観点から下記の記述法を使用する。

正）

誤）

上記は、あくまでも１例にすぎません。上記で挙げた以外にも、「case」の使いどころや、引数の判定は「getOpts」を使用する、ログ出力やシスログ出力、ループの作法など、細かく決定していきます。

機能概要

概要設計は、実装するべき機能の目的及び、概要を解り易く簡潔に記述します。ここでズラズラと役所チックに文章を記述すると、だれも見ない設計書になってしまいます。ましてや、シェルスクリプト設計書を必要とする場合は、きわめて緊急性を要する場合が多い為、一目で把握できるレベルで記述することが大事です。

属性仕様

プロジェクトごとに呼び方は変わると思いますが、この属性設計では、スクリプトファイル名や記述言語等、作成するシェルスクリプトの属性に関わる情報を記述します。

記述する項目としては下記の詳細になります。

この「属性仕様」セクションは非常に重要です。障害発生時に一番初めに知りたい情報がここにちりばめられています。

例えば「種別」なら、このシェルスクリプトは単独実行するのか、他のスクリプトから呼び出されるサブスクリプトなのか・・等で対応範囲が即座に判断できます。

また「リラン可否」の項目では、障害復旧時の現状回復に取る処置は、「単純リラン」で良いのか、エンジニアの判断が必要なのか・・等、俯瞰的に見て取ることが可能となります。

処理詳細

処理詳細には、作成するシェルスクリプトの処理内容を下記の観点毎に文章で記述します。

処理詳細の記載レベルは、プロジェクトによって異なります。最近は少なくなりましたが、行数やインデントなどをすべてを作成するスクリプトと一致させて記述することを求められることもあります。

個別仕様

個別仕様では、そのシェルスクリプトが他のスクリプトと異なる仕様を記述します。例えば、引数の内容や参照する外部ファイル等、作成するシェルスクリプト固有の情報を記述します。

※ 実際のプロジェクトでは、現場毎でノウハウが蓄積されています。実際のスクリプト設計書は、プロジェクトの方針に従って作成してください。