コメントからはじめよう

今回はかなり実践的な話題です。関数をきっちり仕上げる方法を紹介します。まずきっちりした関数とはどんなものかということを定義しなければなりません。

このような条件を満たすためのガイドラインは「コメントを書く」ことです。関数のコーディングを開始する前に、その仕様をコメントで書くようにします。コーディングしながら書くのではなく、コーディングしてから書くのでもなく、コーディングする前に書くのです！

では、どのようなコメントが上の条件をみたすのか、ひとつひとつ考えていきましょう。

関数の使用目的は言葉で表現するのが一番です。普通の日本語で書けば良いでしょう。

はじめに使用目的をコメントで書くのはあとでその関数を使う人の（または使う時の）ためだけではありません。明確に言葉で表現することによって、これから自分が作ろうとしているものを自分自身に言い聞かせるためでもあります。あたまの中がもやもやしたままでコーディングをはじめるとろくなものができないので、作るべきものをハッキリさせてから作るようにします。

私の経験から考えると、自分では何を作るか分かっているつもりでも、実際に言葉で書いてみるとぜんぜん考えがまとまっていないことに気付いたりします。関数をひとつ書く前に、その機能をコメントで書く習慣が大事です。

その関数が入力できる値の範囲を明確に記述する必要があります。たとえば次の関数（文字列の長さを得る関数ですね）

のパラメータ pc には 0 (=NULL) を入力することができません。pc が文字列へのポインタしか受け付けないためです。このように、関数には入力できる値とできない値があります。入力を受け付けることができる値の範囲を明確にコメントするようにしなければなりません。（もし 0 を入力したらどうなるかって？ASSERT にひっかかるか、クラッシュするか、UNIX ならコアダンプするでしょうね。）

このコメントには、関数の安易な修正を抑制する効果があります。たとえば、関数のある利用者が、正常な値を返さないような特定の入力を発見したとします。もしこの関数にコメントがなければ、そのような入力が何らかの意図のもとに受け付けられないようにしてあるのか、それともバグなのかが分かりません。おそらくその利用者は関数を「改良」して、自分の入力に適合させようとするでしょう。しかしこれはまぎれもなく仕様変更です！このような安易な修正による混乱を避けるためにも、禁止された入力を明記しなければなりません。

なお、実際のコーディングでは、もし正しい範囲外の入力を受け取ったときは ASSERT で検出するようにします（ASSERT については別の機会に詳しく述べることにします）。

これは当たり前ですね。入力に対する出力や動作は正確にコメントしましょう。

ここでエラーと呼んでいるのは、入力が正常な場合に発生したエラーです。おもにファイル操作やメモリ確保など、あるていどの確率で発生する可能性のあるエラーのことです。不正なパラメータ値を入力したなどのエラーのことではありません（これはエラーというよりバグ）。

エラーの検出方法をコメントで明記することは重要です。戻り値で返すのか、例外を throw するのかなど、利用者が正確に判定できるようにします。

その関数でできないことを明記する必要があります。たとえば文字列の文字数をカウントする関数なら「この関数では漢字コードはEUCしか扱えません」とか。

コメントは使う人のためだけに書くのではないということを認識してください。自分自身のためでもあります。コメントを書くことによってこれから自分が作ろうとしているものが何なのかが明確になることはすでに述べた通りです。それに、私の観察によれば、コメントを時間をかけてしっかり書いた方が結果的な開発期間は短くなります。

次のトピックでは、あとで関数を使う人（または使うとき）のために何をやっておくべきか検討しましょう。