最終更新日 2020/04/29 © 2020 by T.IZUMI

モジュール入出力の説明の抽象度

「あなたが設計したモジュールの説明をしてください」と指示されたとき、 どう説明したらわかりやすく伝わるか、考えましょう。 物事を説明するときの一般論として、概要から詳細に、全体から細部に、抽象から具体に、が基本的な流れになります。 まずは、全体像として「入力、処理内容、出力」を説明することになるでしょう。

入力は何ですか？出力は何ですか？

次のプログラム例(C言語で記述された関数)をみて、 どんな処理をしているか読み取ってみてください。 そして説明を考えてみてください。

int UpdatePosision(float *curpos, float *move, float *newpos, int n){
  int i;

  for (i=0; i<n; i++)
    newpos[i] = curpos[i] + move[i];

  for (i=0; i<n; i++)
    if ( newpos[i] < -AreaSize || newpos[i] > AreaSize )
      return False;

  return True;
}

説明１

入力

浮動小数へのポインタ curpos

浮動小数へのポインタ move

浮動小数へのポインタ newpos

整数 n

出力

整数（戻値）

関数の入力は引数で、出力は戻値で、それぞれの型がそうだから…、 って、いやいやいやいや、それコードのまんまですやん。 記述レベルの抽象度です。 「コードに入出力の説明のコメントを入れてください」というと こういう説明を入れる人がいるんですが、それはほぼ意味なしです。 プログラミングそのものを話題にしていて記述レベルの説明が必要ならともかく、 普通はこのレベルの説明を求めていません。

説明２

入力

浮動小数の配列 curpos

浮動小数の配列 move

配列の大きさ n

出力

浮動小数の配列 newpos

整数（戻値）

モジュールの中で、何を読みだして、何を書き込むのか、その動作を考えると 情報の流れが見えてきます。 curpos[i]とmove[i]を使っているのでこれらが入力、 newpos[i]に代入しているのでこれが出力、になっていることがわかる。 動作レベルの抽象度です。

説明３

入力

ベクトル curpos

ベクトル move

ベクトルの次元 n

出力

ベクトル newpos

論理値（戻値）

そのモジュールが何らかの数学的なモデルに基づく処理をしているとすると、 数学的な意味から数式レベルの説明をすることができます。 数式レベルの抽象度です。 例えばこのコードでは、配列で実装されたベクトルが入出力、 整数で実装された論理値が戻値、と読めます。 すると、上記のような説明になります。

説明４

入力

現在位置 curpos

移動量 move

空間の次元 n

出力

移動後の位置 newpos

移動後に範囲内にあるかの判定（戻値）

さらに踏み込むと、 そのモジュールが実際の応用プログラムでどう使われるのかを 入出力がどんな対象を意味するのか、という観点からの説明になります。 いわば応用レベルの抽象度です。 例えば、 空間上でのロボットの位置と移動を処理する関数だとして、 入力は物体の位置と移動量、出力は移動後の位置になります。 そして、予めロボットが活動する空間の範囲が制限されていて、 その範囲にあるかどうかの判定も併せて行い、 判定結果を戻値として出力しています。

結局、どう説明すればいい？

結論から言うと、ケース・バイ・ケースです。 順を追って説明していくのなら、 抽象から具体に、応用レベル→数式レベル→動作レベルの流れで説明することになるでしょう。 システム全体の話をしているのなら、応用レベルで。 数式の話をしているのなら、数式レベルで。 実装方法の話をしているのなら、動作レベルで。 これはＣ言語の例ですが、他の計算機言語でも同様です。

変数名＆関数名について

最後に、変数名＆関数名について考えてみてください。 冒頭でプログラム例 UpdatePosision() を示して 「読み取ってみてください」と指示しました。 もしもそれが次のプログラム例 func() だったとしたら、 どうでしょう。 読み取れますか？

int func(float *a, float *b, float *c, int d){
  int e;

  for (e=0; e<d; e++)
    c[e] = a[e] + b[e];

  for (e=0; e<d; e++)
    if ( c[e] < -X || c[e] > X )
      return Y;

  return Z;
}

何をどうしたいのか、意味や意図をよく考えて整理して、 それをわかりやすく表した名前を付けましょう。 困るのは、先生ではなく数週間後の（もしかしたら数分後の）自分です。