チリペヂィア

リンクフリー。サンプルコードなどは関連記事内でライセンスについて明示されない限り商用利用なども自由に行って構いませんが、自己責任でお願いします。またこれら日記内容の著作権自体は放棄していません。引用部分については引用元の権利に従ってください。

Readmeを書くことは良いことずくめなんじゃないか

意外とReadmeを書こうという記事を見たことがあんまり無いので書いてみます。

Readmeの唯一の欠点は、「基本的にあまり読まれない」ことなんですが、でもそれ以外では良い事がたくさんあると思います。作る前から/作りながら書いても良いと思う。でも書いてみて初めてわかることばかりなので、自分の経験からメリットを書いてみます。

一つ。最初から最後の事を考えておくべきだ。

とりとめがなくなることを防ごう。リリースするためにプログラムを書いて、少なくとも最後にはReadmeを添えよう。ただの趣味ならいいけど。

一つ。ある程度の著作権知識も身につく

フリーだとしても公開物は全てライセンスを考えておかなきゃいけない。Readmeに含めるかは微妙だけどどっちみち必要。コピペするにしても少しは読まなきゃいけないし、多少はググらなきゃいけない。実はそれだけでもけっこう知識が身につく。

一つ。YAGNIの基準に出来る。

ある機能の拡張方針で悩んでいるとする。そんな時は、Readmeに使い方を書きやすいように設計しよう。落ち着いて操作手順を推敲したとする。Readmeはただのテキストだから詰め込める情報は結構少ないけど、それでもその制約下でうまく簡単に説明できない時は、そのアイデアはちょっとアレゲな疑いがある(*1)。

一つ。やむなくアレな仕様を採用せざるを得ないとして、被害を最小限にするため、詳しい使い道をプログラムの外の手順書や注意書きにしてしまう手もあるじゃない

たまに、アレな仕様だけどハードの制約とかで採用せざるを得ない場合。そのアレな追加仕様のせいでいろんなところに修正項目が大きく波及してしまうなら、ちっと考えてみて、もしそれがレアケースとかなら、何もボタン一個でプログラムが内部で全てファジーに対応するとか、専用の特殊モードが発動するような話ではなく、手順書に注意書きを目立つように、あるいは検索可能に残しておくだけで良かったりするんじゃないの?

一つ。エラーメッセージ一覧

きちんとしたプログラムはエラーに強い。エラー設計がきちんとされているなら、エラーメッセージ一覧を作るのもきっと簡単。そしてその一覧はユーザーにとってすごくありがたい。一方、エラー時のシナリオがボロボロなプログラムはエラーメッセージ一覧を作るのも大変だ。一覧がなければユーザーはマニュアルを自分でスミズミまで読み直す羽目になる。よくない。

他にもあるんじゃないかなと思いますが、とりあえずこんなところです。なんかすんごい泥臭い話になっちゃったな…

*1:だいたいゼロベースの時はトップダウンでニーズを出してボトムアップで実装するんだけど、拡張を考える時はボトムアップ可能な範囲でトップダウンのうち拾えるところを拾う構図になる事が多くて、そうやってぼちぼち穴埋めしていくと、実装者としてはご満悦なんだけど、パッケージ全体としてはよくわからん感じになりやすい。そこをもう一度、「純粋なトップダウンの視点でまとまっているかどうか=Readmeに書けるかどうか」で考えてみると良い。ディレクターやコミッターにマイルストーン相談する前にある程度目星がつくと思う。