目次 前 次

---

コメントをどう入れる

　ソースコードに、コメントがある方が概要を
　掴まえるのには、便利です。

　コメントは、機能を説明するのか、動作を説明
　するのかを分けておいた方がよいでしょう。

　コメントを機能で入れるときには、何を目的に
　しているのかを明らかにしておかないと、後で
　見返すときに、？となることがあります。

　サブルーチン、関数の場合、コメントには
　呼出し側のシーケンスや返値の内容を記す
　ようにして、目的を明らかにしておきます。

　例えば、次のような関数があったとします。

typedef unsigned char  UBYTE ;
typedef unsigned short UWORD ;

UWORD calc(UBYTE x,UBYTE y)
{
  UWORD result ;

  result = (x + y) >> 1 ;

  return result ;
}

　この関数は、２変数の平均を求めるだけです。

　コードを見ないで、その機能を説明するにも注意
　しないと、バグ発生の場面に出くわします。

　入力パラメータは２つあり、その範囲は
　０から２５５に制限。
　計算結果は、16ビットの正の整数か０になります。

　入出力の制限と限界をコメントに入れてないと
　自分ではないユーザーが使うときに、想定外の
　バグを発生させる可能性があります。

　変数、関数の範囲には、unsignedが付いている
　ために、正の整数か０しか扱わないと宣言して
　いますが、Cの言語仕様を知らないユーザーが
　使うことを考えて、コメントに制限事項を入れ
　無駄な時間を費やさないようにすべきでしょう。

　プログラムを記述した時の自分とは他人だと
　考えて、他人にわかるようにコメントに入れて
　いくと考えると、何を書くべきなのかが見えて
　きます。

---

目次 前 次