脳log[20190105]

2019年01月05日 (土) ドキュメントについて。目の前に動いている機械があるときに、その構造を読み取らずに説明書を読み始める法はないと思うんだよね。その機械を修理・改造しようとしている人間であればなおさら、構造から直に学んで説明書の誤りを指摘できるぐらいでないと役に立たない。というわけでドキュメントは、「お客さんに向けた取扱説明書」か「基本がわかっている人間に向けた内部を理解する時間を節約するための勘所」のどちらかになると思ってる。「わかっているべき基本」というのは道具の知識、対象一般の知識のこと。そういう固有でない部分を解説するのも読まされるのも双方の時間の無駄だと思ってる。あとは DTD みたいな、そのままコードの入力にすればいいじゃんというようなドキュメント。読むには重いし、コードでないから信頼できないし、コードと二重に維持するのがつらい。ドキュメントをコメントに置き換えたら、コードをそのまま日本語に翻訳したようなコメント(ドキュメント)が良くないというのも耳タコに繰り返されてきたことだ。『リーダブルコード』とかまだ読んでないけど、たぶん書いてあるのではないか。『プログラミング作法』か『Code Craft』でもいいだろう。■「tools/recipeProcessor.bat」に使用法のコメントがないのは、単に使い方を知りたがるほど興味を持った人間がいなかったからだ。引数の意味と実行結果とレシピファイルのフォーマットの解説くらいは必要だと思ってる。バッチファイルにコメントが少なくなるのは、行を分けないと書けないというのが多少影響してる。