2012年03月18日

ITを使いこなすための、使いやすいサンプルの作り方

ソフトウェア・ツールや、プログラムのライブラリを使うときに、使いこなせるようになる最も早い方法は、良いサンプル・プログラムをコピーして動かすことです。

では、悪いサンプル・プログラムは、どういうものでしょうか。

まず、コードの量が多いプログラムです。 ユーザーを感動させるようなソフトウェアをサンプルと呼ぶことがありますが、これは、ソースが公開されたデモ・プログラムです。 サンプルの目的である、理解することには役に立ちません。 無いよりはマシですが、デモが複雑に作られていることしか伝わらないでしょう。 まず、基本を押さえることができなければ、いくら豊富なサンプルであっても、すべてがゴミのように見えて頭に入りません。

次に、パラメーターを持った関数の中から、API に、そのパラメーターを渡しているサンプルです。 パラメーターが多い API があって、パラメーターを減らす効果があるサンプルのつもりでしょうが、API を呼んでいる関数の仕様のドキュメントが無かったり、変数名が省略形であることが多いために、理解不能なのです。 API に渡したパラメーターが式になっていたら、なぜその計算をしているのかをサンプルから知ることはできません。 これも、API の理解ではなくサンプルを理解する必要が生じるのです。 それに、サンプルはテストが甘いので、バグが入る可能性が高いのです。

void SampleSet( int Number, char* Buffer, size_t BufferSize )
{
  SetAPI( Number + 1, Buffer, BufferSize / 2, NULL );
}

良いサンプルは、API に変数ではなく値を指定し、その結果も付けたものです。

char buffer[256];
strcpy( buffer, "abc" );
SetAPI( 1, buffer, _countof( buffer ), NULL );
  // 1つ目の要素に buffer の内容を格納します

また、1つの関数呼び出しでは、機能の一部しか行わないために、中途半端な結果となる場合は、関連する関数もサンプルに加える必要があります。 結果を厳密に表現するためには、assert を使うとよいでしょう。

char buffer_1[256];
char buffer_2[256];
char buffer_3[256];

strcpy( buffer_1, "abc" );
strcpy( buffer_2, "def" );
SetAPI( 1, buffer_1, _countof( buffer_1 ), NULL );
SetAPI( 2, buffer_2, _countof( buffer_2 ), NULL );
GetAPI( buffer_3, _countof( buffer_3 ), NULL );
assert( strcmp( buffer_3, "abcdef" ) == 0 );

そして、サンプルが動くプロジェクト・ファイルを付ければ完璧ですが、すべての仕様に対してサンプルをつけてテストするのは、コストがかかりすぎるので、一部の基本的な仕様についてだけでよいでしょう。

そして、ライブラリを最も素早く利用する方法は、サンプルをテンプレートとして使い、コピーして必要な部分だけ修正することです。 ユーザーがすぐに使えるようにサンプルを用意することが、使いやすい API 仕様にすることより、劇的に効果があります。

更に、Snap Note などを使って、サンプルをすぐに取り出せるようにできれば、記憶が要らなくなるので、もっと多くのツールを使いこなすことができるようになるのです。

アップルは、使いやすく感じさせる映像を作ることが得意です。 そこには、良いサンプルがあります。 しかし、いざ自分が使うとなると、何をしたらいいか分からない。 使う状況での良いサンプルが不足しているからです。 すなわち、アップルは使いやすさを本気で提供しているわけではありません。

sage_p at 23:20│Comments(0)TrackBack(0) プログラミング 

トラックバックURL

この記事にコメントする

名前:
URL:
  情報を記憶: 評価: 顔