PlantUMLで数式を書いてみる。
高木です。おはようございます。
私はプログラマーですので、職業柄ドキュメントを書くこともそれなりにあります。
仕様書も書けば設計書も書きますし、doxygenでドキュメントを自動生成するためのコメントも書きます。
ソフトウェア関連のドキュメントを書くとなると、（良し悪しはともかくとして）ExcelやPowerPointを使う人が多いようですね。
私もPowerPointを使うことはありますが、あくまでもスライド用というかプレゼンなり打ち合わせなりで発表するための資料を作る目的です。
それ以外は、特に要望がなければ、プレーンテキストで編集できる方法を選びます。
最近ではMarkdownが流行っているようですね。
しかし、表現力の高さから、私はdoxygenを使うことのほうが多いです。
弊社の就業規則でさえdoxygenで作成しています。
そんなdoxygenですが、PlantUMLのコードを埋め込めるようになってからは、UMLだろうがGUIだろうがプレーンテキストで記述できるようになりました。
数式もそうで、AsciiMathまたはLaTeXの形式で記述することができます。
もともとdoxygenにも数式を記述する方法があるのですが、いろいろインストールしないといけないものもあり、環境によっては決して使いやすいとはいえません。
doxygenの数式の記述方法はLaTeXなので、私もそちらに慣れていました。
PlantUMLでLaTeX記法を使うにはJLaTeXMathをインストールしないといけませんが、AsciiMath形式の場合は追加インストールは不要のようです。
最初はLaTeX形式のほうが慣れていることもあって、JLaTeXMathをインストールして使おうとしていました。
しかし、ちょっと試してみるとAsciiMath形式のほうが使い勝手はよさそうです。
何といっても記法が直感的です。
具体例を挙げましょう。
下記は中学校で習う二次方程式の解の公式です。
PlantUMLのAsciiMath形式では次のように記述します。
1 2 3 | @startmath x = frac{-b+-sqrt{b^2-4ac}}{2a} @endmath |
比較のためにLaTeX形式でも書いてみると、次のようになります。
1 2 3 | @startlatex x = \frac{-b\pm\sqrt{b^2-4ac}}{2a} @endlatex |
この程度であれば大差ないと感じるかもしれません。
しかし、複雑な式になればなるほど、煩雑な記述をしなければならなくなります。
そういえば、WordやPowerPoint（そしてExecel）にも数式エディタが付いています。
私も試したことがありますが、本当に簡単なものならいいのですが、ちょっと複雑な式を書こうとすると、操作が面倒なだけでなく、非常に重い上にたびたびフリーズします。
以前の開発で使おうとしたことがありましたが、すぐに諦めてdoxygenに切り替えた経験があります。
ドキュメントの書き方というのは、人それぞれ、また職場によっても流儀があるようです。
何かと図や表を使いたがる人も多いように思います。
図は視覚的に表現できていいのですが、何となくわかった気にさせるにはいいものの、厳密な定義には向いていません。
表を使えば厳密に定義できますが、早い話がベタベタな記述であり、「この場合はこうなって、あの場合はああなる」みたいな感じで場当たり的すぎます。
やはり一貫的な振る舞いを定義するには数式のほうが向いています。
コードに落とすのもそのほうが楽ですし。
数式といっても、あまり難しいものを使ってしまうと理解できる人が激減してしまいます。
理解してもらえないドキュメントを書いても自己満足にすぎません。
そういうこともあって、可能な限りは中学生レベル、必要なら高校生レベルの数式にとどめています。
仮にも技術者を名乗るのであれば、それぐらいは理解できるだろうと期待するからです。
中学生レベルの数式を理解してもらえない場合は困ってしまいますが、そういう人は技術の仕事は向いていないと思います。