マークダウンでプログラム処理をわかりやすく書く記法

マークダウンで条件分岐や繰り返し処理などのプログラムの具体的な処理を書こうとしたときに、どのように書けばわかりやすいのか迷われたことはないでしょうか。

私はこのようなプログラム処理を書く場合はExcelを使うことが多く、その時には気にも留めていなかったのですが、いざマークダウンで書くとなった時には装飾が制限されていることから、思ったような表現ができず困ってしまうことがありました。

そんな時に、「マークダウンの記法は決まっているのだから、プログラム処理の書き方も決まっていてそれに沿うのが良いだろう」と思い探してみましたが見つけられなかったので、自分で考えてみることにしました。今回はこの自分で考えてみたマークダウンでプログラム処理をわかりやすく書く記法について説明したいと思います。

ポイントとしては、プログラムの三つの基本構造「順次実行」、「条件分岐」、「繰り返し」をどのように表現するかに焦点を絞っているところです。

書き方のイメージ
書き方のルール
終わりに

書き方のイメージ

この記法を使って書いたマークダウンは下の通りです。動物一覧ファイルを読み込み、動物の種類ごとのファイルにデータを出力する処理となっていますが、何となく「順次実行」、「条件分岐」、「繰り返し」が伝わる形となっているのではないでしょうか。

ソースコードはこのようになっています。

動物一覧ファイルを開く。

* IF: 動物一覧が0件の場合。  
  メッセージ「動物一覧が0件のため、処理を終了します。」をログ出力する。  
  処理を終了する。  

* LOOP: 動物一覧の件数分ループ。
  * IF: 動物の種類が哺乳類の場合。  
    哺乳類ファイルにデータを出力する。  
    
  * ELSE IF: 動物の種類が鳥類の場合。  
    鳥類ファイルにデータを出力する。
  
  * ELSE IF: 動物の種類が魚類  
    または、動物の種類が両生類  
    または、動物の種類がは虫類の場合  
    
    魚類・両生類・は虫類ファイルにデータを出力する。
  
  * ELSE:  
    例外ファイルにデータを出力する。

メッセージ「処理を終了します。」をログ出力する。

それでは詳細について説明します。

書き方のルール

順次実行

他の条件分岐や繰り返し処理と区別するために、何も装飾はしません。他の処理と組み合わせて使う場合はインデントを合わせるようにします。

条件分岐

箇条書きリストを使用し、頭に目印としてIF:をつけます。条件を追加する場合はELSE IF:を、条件に一致しなかった場合の処理を記載する場合はELSE:を代わりの目印として付けます。

条件が長くなってしまう場合は、下のように見やすいよう改行を入れます。その次に空白行を入れ、条件に一致した時の順次実行処理が何なのかわかりやすくします。

入れ子構造となる場合は、箇条書きリストのインデントを利用して、入れ子となる処理のインデントを下げるようにします。

繰り返し

箇条書きリストを使用し、頭に目印としてLOOP:をつけます。実際のプログラムで書くときはfor文やwhile文を使いますが、マークダウンの時点でそれらを記載しまうと実装時に先入観を持ってしまうと思い、どちらでもないLOOP:という目印にしました。

条件分岐と同様に入れ子構造となる場合は、箇条書きリストのインデントを利用して、入れ子となる処理のインデントを下げるようにします。

終わりに

マークダウンでプログラム処理をわかりやすく書く記法について説明しました。ウォーターフォール開発での詳細設計や、プログラミング初心者向けの説明資料などをマークダウンで書く際の参考となれば幸いです。

サンプルとして提示したイメージはこちらのGitHubにもありますので、よければ参照ください。