開発現場特有のドキュメントの書き方

伊東 輝

システムの開発・運用の現場では、業界特有のフォーマットのドキュメントが使われることがある。
業界内では一般化しているフォーマットであり、そのフォーマットに従うことで、技術者同士の意図の伝達をスムーズに行うことができるようになる。

この記事では、そのようなフォーマットの中で特に使用頻度が高いフローチャートとシーケンス図について取り上げていく。


(1)フローチャートの書き方

フローチャートとは、処理の流れを図に起こして整理するために使うフォーマットである。
フローチャートを起こすことで、他の人に処理の流れを伝えやすくなるので、設計書では良く用いられる。
また、自分自身も処理の流れを理解しやすくなるため、複雑なプログラムを実装する前に作ることもある。

【フローチャートの記法】

フローチャートは、記号を線で結ぶことで作成する。
記号の中には具体的な内容を記述する。

フローチャートでは主に以下の記号が使われる。

図1-1：フローチャートの記法

上記の記号は、プログラミングの基本となる順次・分岐・繰り返しに相当する記号と、複雑な処理を分割する際に必要な記号である。
他の記号が使われることもあるが、上記の記号だけで事足りることが多いだろう。

【フローチャートの例】

フローチャートは、詳細なものと概要を把握するものに大別できる。

詳細なフローチャートは、プログラムの１行１行を記号に落としていくようなイメージであり、すぐにプログラムに落とし込むことが難しい初学者にお勧めできるフローチャートである。
一方、概要のフローチャートは、処理の流れを俯瞰するためのものであり、実際のプログラミングでは１つ１つの記号の中で複数の処理を記述する。設計書に用いられることが多いのはこちらのフローチャートである。

図1-2：詳細フローチャートと概要フローチャートの例

繰り返しや定義済み処理を含む複雑なフローチャートの例を以下に補足する。

図1-3：複雑なフローチャートの例

【（参考）アクティビティ図の書き方と例】

オブジェクト指向技術を設計に用いる場合の用いられる共通的なフォーマットの規格として、「UML」というものが存在する。
UMLにおいては、「アクティビティ図」が「フローチャート」に相当する。

UMLの図の作成をサポートするツールとして「PlantUML」と呼ばれる図が公開されている。
このツールでは、独自のルールでソースコードを記述することで自動的に図が生成されるため、このツールを用いることで生産性を高めることができるだろう。

PlamtUMLのトップページには、UMLで定義されたそれぞれ図について、独自のソースコードのルールが書かれたリンクが貼られている。
ルールを説明するついでに記法についても書かれているので、詳しい記法はそちらを参照すると良いだろう。

アクティビティ図はフローチャートによく似た記法や特徴を持つが、アクティビティ図独自の利点としては、並列処理を示す記法が定義されている点がある。
（ただし、並列処理に主眼が置かれるのであれば、後述のシーケンス図を用いるべきだろう）

以下は、PlantUMLでアクティビティ図を作成した例である。

図1-4：アクティビティ図の例（PlantUMLにより記述）

図1-4のソースコード

@startuml
start
:第１引数を受け取る;
!pragma useVerticalIf on
if (第１引数が全桁半角数字) then (Yes)
else (No)
  :第１引数を0に変換;
endif
:第１引数を返す;
stop
@enduml

(2)シーケンス図の書き方

シーケンス図は、アクター（「オブジェクト」「プロセス」「機器」「関係者」…等の任意の主体）の間のやりとりを時間軸に沿って表現する図である。
複数の処理が並列で走る場合に、処理タイミングを整理する上で便利な図である。

シーケンス図も、前述のアクティビティ図と同様にUMLで定義された図である。
しかし、実態として、オブジェクト指向技術を用いる場でのみ使われるわけではなく、フローチャートと同様に汎用的に使われる図である。

【シーケンス図の記法】

シーケンス図は、各アクターの存在を示すライフラインと、ライフライン間のやりとりを示すメッセージによって記述される。
具体的な記法としては以下である。

図2-1：シーケンス図の記法

上記以外にも細かい記法は存在するが、シーケンス図の根幹をなすのは上記の記号であり、上記の記号を覚えておけば最低限の意思疎通はできるだろう。

なお、上記以外の記法は、「alt/else」＝「分岐」、「loop」＝「繰り返し」といった具合に言葉で書かれることが多い。
そのため、仮に覚えていなかったとしても意思疎通に大きな支障はないだろう。

【シーケンス図の例】

シーケンス図の例として、「マルチスレッドプログラミング」と呼ばれる、プログラムの実行単位（プロセス）の中で複数の処理主体（スレッド）を生成する技術の例を挙げる。

以下の図では、ThreadBody_1の処理とThreadBody_2の処理が入れ子にならないように、ThreadBody_1の処理が終わってからThreadBody_2の処理を行う、という制御を行うことを示している。
このように、複数の主体で処理のタイミングを取る必要がある場面で、シーケンス図は便利である。

なお、シーケンス図も、前述のPlantUMLによりサポートされているため、PlantUMLを使うと楽に作図できるだろう。

図2-2：シーケンス図の例（PlantUMLにより記述）

図2-2のソースコード

@startuml
participant ThreadMain as tm
participant ThreadBody_1 as tb1
participant ThreadBody_2 as tb2
participant ThreadCounter as tc
tm -> tb1 : スレッド起動
loop 5 times
    tb1 -> tc : カウントアップ
    tc -> tc : カウント表示
end
tm -> tb2 : スレッド起動
loop 5 times
tb2 -> tc : カウントアップ
tc -> tc : カウント表示
end
@enduml


この記事が気に入ったらサポートをしてみませんか？