モジュールのドキュメント

関数やクラス、プロパティなどのプログラムモジュールを作成時、
プログラマの誰しも、ドキュメントを書くのは億劫だろう。

コード読めよ
と。

コードを読めばAPIもロジックもわかるよね。
コードをアプデしたのに、”どこか余所”にあるドキュメントを更新するのをつい手抜きしたりするんだよな。

それで”賢い”エンジニアが『DocString』を発明した。
これでドキュメントが散逸することなく、常にソースコードと一体で保全される・・・これにて一件終了・・・
と考えたわけね。

かくしてプログラマにはまたひとつ憶えることが増え、仕事が増える。
みんなお行儀のよいプログラマなんだろうから、これでいいのかもしれないけど。

厄介なのは、もしその『DocString』が中身と違っていたり間違っていても、コンパイラやインタプリタは叱ってくれないこと。
せいぜいたまたま暇なボスや親切な同僚が見つけて指摘してくれたらラッキーだけど、ほぼほぼそれが露呈するのは”致命的な問題”が起きた時だから泣ける。

だってそのコメントはあまり誰にも見られることはないんだから。
書いてあることが信用されないから見られないのか、どうせ誰も見ないんだからと手抜きするのかわからんが。

不思議なのは
遠いどこかの誰かが作ったフレームワークやライブラリは、頭から信用するのに、
同じ会社やチームの作ったプログラムやドキュメントはあまり信用しないこと。
それは人間不信じゃない。
自分の職場のプロジェクト管理への不信。

コードとドキュメントを共有する仕組み

例えばモジュールの入力パラメータをこんな風に定義しとく。

$mod = HARDTIP_PREFIX.'/block/vue';
　　：
  "$mod/@scheme/tips" => '...resizable;foldable?:foldable/fold?...',
　　：
  "$mod/@scheme/tips/resizable/description" => 'リサイズ部分：上下左右を指定',
  "$mod/@scheme/tips/resizable/type" => 'array',
  "$mod/@scheme/tips/resizable/options" => 'right;left;top;bottom',
  "$mod/@scheme/tips/foldable?/description" => '開閉可能か？：ヘッダ部分をクリックして開閉する',
  "$mod/@scheme/tips/foldable?/type" => 'bool',
  "$mod/@scheme/tips/foldable/fold?/description" => '開閉初期状態',
  "$mod/@scheme/tips/foldable/fold?/aliases" => 'fold;foldable/fold?',
  "$mod/@scheme/tips/foldable/fold?/type" => 'bool',
  "$mod/@scheme/tips/foldable/fold?/default" => false,
　　：

このパラメータはモジュールでは、こうやって受け取ることができる。

$tips = ESP::_tipsGetWhole($mod, $name);

if(!empty($tips['title'])){
  $prms['title'] = [
    'notUse'=>!$tips['title?'],
    'text'=>$tips['title'],
  ];
}
$prms['class'] = $tips['class'];
$prms['blocks'] = $tips['blocks'];

このモジュールの仕様を見たければ、このurlでアクセスすると

https://dojo.esp.center/.esp/hardtip/block-vue

こんな風にフォーマッティングされて表示される。

この”記述”の中でエンジニアにとって唯一”無意味”なのは「description」つまり”説明”だけど、
これはこのモジュールをオーダーした人に書いてもらうべきだろう。
何がしたいのかはほとんどの場合モジュールの”外”からやってくる。

ちなみにこのurlの`dojo.esp.center`はその時自分が携わっているプロジェクトのホスト名。
えーとドキュメントのurlはなんだっけ？
と悩む必要もない。

https://dojo.esp.center/.esp

これはESPシステムのユーティリティのサイトで
ここからリンクを辿ってもいける。

『システム開発フレームワーク』なら、このくらいは当たり前だと思うんだけどね。

これがESP。