著者アーカイブ 杉浦

著者:杉浦

PlantUMLの機能が思ったより多彩

　PlantUMLはUML図を表現できる言語です。言語故にテキストファイルであり、変更やGit管理が楽で便利です。
　PlantUMLを書いていると、あまりに図が複雑になるため複数ファイルに記述を分けたい時があります。そういった時、何度も同じ意味で同じ名前を宣言する記述が重複しがちです。そういった問題はinclude機能で定義ファイルの読み込みのみを記述することで解決できます。
　Use the preprocessorのIncluding files or URL

// define.puml
@startuml
participant "ブラウザ" as br
participant "サーバ" as svr
@enduml

// child.puml
@startuml
!include define.puml
br-->svr: ページ要求
@enduml

// child2.puml
@startuml
!include define.puml
br<--svr: ページレスポンス
@enduml

　こうすると、あるファイルだけ違う変数名で同じものを指している、という混乱やコピペコードを防げます。
　デフォルトのPlantUMLでER図を書いている時、定義の記述を一行にきれいなデザインでまとめることにくたびれます。デフォルトで等幅フォントを採用しておらず、空白を使って縦を合わせるのがめちゃくちゃしんどいです。等幅フォントを使うように宣言しましょう。
　Which fonts are available ?

@startuml
skinparam {
  defaultFontName Monospaced
}

entity users {
  # id                  int(11) unsigned auto_increment
    name                varchar(255)         not null,
    login_id            varchar(50)          not null,
    password            varchar(255)         not null,
    password_changed_at datetime             not null,
    email               varchar(255)         not null,
    last_login          varchar(25)          not null,
    login_failed        tinyint              not null,
    locked              tinyint              not null,
    locked_at           int                  not null,
    status              tinyint    default 0 not null,
    login_hash          varchar(255)         not null,
    created_at          int        default 0 not null,
    updated_at          int        default 0 not null,
    deleted             tinyint(1) default 0 not null,
}

@enduml

　ここでは特に使うと確信した二例を紹介しましたが、公式の前処理、共通事項をはじめとしたUMLから離れた欄を隅まで見ていくと思わず教えて欲しかったとなる便利機能がわいてきます。
　シンプルなテキストファイルで UML が書ける、オープンソースのツール

著者:杉浦

KISS原則のためのデザインパターン

　デザインパターンは今までに至るまで作られてきたコーディングの際のパターンです。大体これは複数ファイルにまたがるつくりになっており、とてもとても複雑な問題をなるべくシンプルにされたパターンを知るだけで解決できるようにします。図は増補改訂版Java言語で学ぶデザインパターン入門 ｜ 結城 浩 ｜本 ｜ 通販 ｜ Amazonから引用したFacadeパターンのクラス図です。

　KISS原則はKeep is simple stupidの略で「単純な作りを保て」という意味です。短くて意味が明確だと読み解きやすいものです。原則というだけあり、デザインパターンもとてもとても複雑な問題に対してこの原則を実現するために作られていることが多いです。
　KISSの原則 – Wikipedia
　デザインパターンの実現よりも原則の実現を優先すべきです。語弊がある文なので補足ですがコーディングで最も優先すべきは要件の実現です。動くきれいなコード＞動く汚いコード＞動かないきれいなコード、です。
　Gitのソースコードでも業務範囲でもこの二つについてのアンチパターンに本末転倒なパターンが時折見られます。簡単な作りで済むのにデザインパターンを適用したばかりに読み解くのが面倒になります。例えば、Facadeパターンなら次のようなものです。

// 極端にやってしまったパターン
function client() {
    $fasade = new Fasade()
    $fasade->echoA();
    $fasade->echoB();
    $fasade->echoC();
    $fasade->echoD();
}

class Fasade {
    use EchoA, EchoB, EchoC, EchoD;
}

trait EchoA {
    function echoA() {
        echo 'a';
    }
}
trait EchoB {
    function echoB() {
        echo 'b';
    }
}
trait EchoC {
    function echoC() {
        echo 'c';
    }
}
trait EchoD {
    function echoD() {
        echo 'd';
    }
}
// これで十分だったパターン
function client() {
    echo 'a';
    echo 'b';
    echo 'c';
    echo 'd';
}

　無暗にクラスを分けたせいで複雑化しています。例は極端ですがアクティブレコードのみで十分なのに、コントローラ->コマンド->リポジトリ->モデル->SQL文発行、の様な段階が過度に多いものはままあります。簡単な問題を複雑にしていないか、本当にそこまで大がかりなものを用意する必要があるのか、都度考えてコーディングしたいものです。

著者:杉浦

PlantUMLをwebページ的にダンプする

　具体的には各UML図をハイパーリンクによってつなげたSVGファイルにしてブラウザ上で見れるようにします。目的はアクティビティ図->シーケンス図、ER図全体->ER図部分の様な関連した別UML図を閲覧者が探しやすくすることです（WWWの元ネタそのまま）。この様にできるとPUMLを一つの場所に過度に巨大に濃密に記述する必要がなくなります。
　実際にこれを行うための手順は、PlantUMLを記述する際に出力状態のSVGリンクを相対パスで作る、階層構造を維持したままSVGにダンプする、の2ステップだけです。これによってGIFの様にできます。

　PlantUMLに次のように書くことで図のようにハイパーリンク付きの文字列を作れます。使える場所はかなり広く文字列を表示する場所ならどこでもOKな印象です。今回はpumlファイルのあるフォルダと同じ場所にsvgファイルを展開するつもりなので、記述中のpumlファイルの場所からみた特定のpumlファイルへの相対パスを記述します。

:[[greeting/HelloWorld.svg Hello world]];

　特定のディレクトリ下にsvgとしてpumlをダンプするコマンドは次になります。

java -jar plantuml.jar ./**.puml -tsvg -charset utf-8

　現在のディレクトリ以下の.pumlファイル全てを文字コードutf-8のSVGにして.pumlのあるフォルダと同じ場所にダンプします。これだけでできます。特定フォルダ以下に出力するには-oオプションを用います

java -jar plantuml.jar ./**.puml -tsvg -charset utf-8 -o svg

ならば./svg以下にSVGファイルが出力されます。

著者:杉浦

GitHubを使って一般的な変数名を選ぶ

　学生時代、分かりやすい論文を書くために気にするべきことの点として「一般的な語を選ぶ」という点がありました。ここでいう一般的とは、対象の界隈（論文なら学術分野）で広く使われていて共通認識が存在する、ということです。「一般的な語を選ぶ」とは、角速度センサとジャイロセンサの様な同じものを指す語の内より多く使われている方を選ぶ、といった感じの行為です。このどれが最も多く使われているかを簡易に調べる方法としてググった際のヒット件数の比較があります。界隈を限定するべき語（プログラミング言語のRubyと宝石のRubyを分けて検索したいとか）の場合は検索する語を追加したりGoogle Scholarまで行ったりします。先ほどの例ならばジャイロセンサの方が多く使われているので、角速度を計測するセンサを表す時は”ジャイロセンサ”を使うと判断できます。

　コーディングの際に気にするべきことに可読性、検索容易性があります。中長期の開発や機能改善の際にはいくらか忘却したコードを改めて読む必要があります。この時に変数名、クラス名などの様々な値の名前から値の意味が理解できない場合、コードを読み解くのに時間がかかります。また、ある機能について調べる時に値の名前から探そうとするもあり、一般的でない名前が使われているとまともに検索できません。次のツイートは極端な例ですが似たようなことは簡単に起きます。

tmp「一時変数だと思った？」
ぼく「もしかして… 気温か…？」
tmp「添付ファイルだよ」
ぼく「ぐぬぬ…」

— 焼肉のすえなみ (@a_suenami) 2019年6月6日

　この様な名前の問題を避けるためにリーダブルコードでは次の様に指南されています。

名前をつけるときには、それが変数であっても、関数であっても、クラスであっても、同じ原則を当てはめることができる。名前は短いコメントだと思えばいい。短くてもいい名前をつければ、それだけ多くの情報を伝えることができる。プログラムに使われる名前というのはハッキリしないものが多い。例えば、tmpなんかがそうだ。でも、sizeやgetみたいに一見すると問題がなさそうな名前であっても、情報が含まれていないことがある。これから情報を詰め込んだ名前のつけ方を紹介する。本章は、以下の6つのテーマで構成されている。
– 明確な単語を選ぶ
– 汎用的な名前を避ける（あるいは、使う状況を選ぶ）
– 抽象的な名前よりも具体的な名前を使う
– 接尾辞や接頭辞を使って情報を追加する
– 名前の長さを決める
– 名前のフォーマットで情報を伝える

Dustin Boswell; Trevor Foucher. リーダブルコード (Kindle の位置No.228-232). 株式会社オライリー・ジャパン. Kindle 版.

　共通認識の成り立っていると仮定できるくらい一般的な名前ならば、少ない文字数で「明確な単語を選ぶ」「汎用的な名前を避ける（あるいは、使う状況を選ぶ）」「抽象的な名前よりも具体的な名前を使う」の三つが満たせます。また「接尾辞や接頭辞を使って情報を追加する」をした際に過度に長い名前ができあがらなくなります。
　論文における一般的な語の選択の様に、コーディングにおける一般的な名前を選択しようとするならば、コーディング界隈から使用されている数を調べる必要があります。この時、Googleは程々にしかあてになりません。Googleで検索できるのはweb上のコンテンツ全てでありソースコードから離れています。代わりにGitHubの様なソースコードリポジトリを用いることができます。特にGitHubならば言語、フレームワークでソースコードを絞り込むこともでき、より適した範囲から語の検索ができます。
　例えばJavaScript界隈で緯度経度を変数にするならばlat, lngにしておくのが適切だと分かります。