#3 Javaプログラミングデザイン考2

コメントの重要性について

要件追加を繰り返しすっかり「汚いプログラム」の集合体と化したシステム。とは言えいきなりプログラムの最適化を図るのは危険極まりない行為です。ここでは、プログラムの中で書かれるコメントの重要性について言及していきたいと思います。

プログラム改修を繰り返し行われたシステムでは、コメントの記入を往々にして軽視しがちにあります。また、プログラムにコメントを記述することについて、ネット上では次の様に否定的意見も時折見受けることがあります。

• 分かりきったことをいちいちコメントに書くな

• 処理が分からないなら設計書読め

• 仕様変更でプログラムを書き換えてその上コメントのメンテなんて面倒

• プログラムを追えば内容が分かるように書いたしコメントなんて不要

ここで筆者は断言します。

「分かりやすくプログラムを書いた」というのは制作者の主観でしかなく、第三者の目を通してしか正しく評価はできない。解析を初めて「３秒」以内に処理の意図が汲み取れないようなプログラムは総じて「コメントが絶対に必要なプログラム」であると言える。

ここで注目してほしいのは、「解析を初めて『３秒』以内」という点です。メンテナンス効率を追求したい場合、それを最も阻害する要因が解析作業に他なりません。非常に簡単なサンプルを例に挙げて説明していきます。

サンプルを用いた解説 - 問題提起編

01. List<String[]> nameArrayList = ColumnNameDao.getColumnNames("NORMAL") 
02. for (int i = 0; i < nameArraysList.size(); i++) {
03.     String[] nameArray = nameArrayList.get(i);
04.     int idx = 1;
05.     while (idx < nameArray.size) {

            // メインの処理を複数行に渡り記述

x1.         idx = idx + 3;
x2.     }
x3. }

説明しやすいよう行番号を付けましたが、よくあるfor文の記述になります。
なお、行番号01はデータベースから所定の条件でデータを抽出する処理になります。ではここで２点質問です。

• 行番号04で宣言したint変数の初期値が1なのはなぜか

• 行番号x1においてint変数の加算値が3なのはなぜか

この質問を回答するためには、行番号01で返されるString配列のリストがどの様なものかを知る必要がありますが、それを知るためには、
①設計書を読む
②データベースを参照して調べる
といった方法が考えられますが、
①設計書が最新ではない
②テスト環境のためデータパターンが網羅されていない
などの問題で仕様を完璧に突き止められない可能性もあります。
また、仕様が分かったとしても、行番号05から始まるwhile文の内容が100行を超えるような大容量で、解析で疲弊した頭で「idx = idx + 3」と出た時に即座に理解できるか、といった問題も考えられます。

サンプルを用いた解説 - 回答編

01. // 複数のカラム名をカンマ区切りに繋いだ文字列をString配列に分割したリストを取得
02. List<String[]> nameArrayList = ColumnNameDao.getColumnNames("NORMAL") 
03. for (int i = 0; i < nameArraysList.size(); i++) {
04.     String[] nameArray = nameArrayList.get(i);
05.     // カラム名はAグループ、Bグループ、Cグループの順の並びを繰り返す
06.     // ここではBグループを対象して処理するためインデックスの初期値1, 増分3とする
07.     int idx = 1;
08.     while (idx < nameArray.size) {

            // メインの処理を複数行に渡り記述

x1.         idx = idx + 3;
x2.     }
x3. }

サンプルでは、ここだけで解決できる最大量のコメントを記述しています。例えばColumnNameDao.getColumnNamesメソッドの方で、取得できるデータパターンに関する記述がコメント記載されていれば、行番号01、05、06のようなボリュームになるほどコメントを書く必要はありません。なお、ここで大事な要点となるのは「処理の意図が伝わる内容になっているかどうか」という一点です。「処理していることは分かってもなぜそう処理するのか意図が分からない」という場面には、これまでに何十回何百回と出くわしてきました。ほんの少しの時間を割いて気遣うことで、不毛な解析作業を回避できるのですから、いかにコメントが大事であるかがご理解いただけたと思います。

サンプルを用いた解説 - NGコメント編

01. // 複数のカラム名をカンマ区切りに繋いだ文字列をString配列に分割したリストを取得
02. List<String[]> nameArrayList = ColumnNameDao.getColumnNames("NORMAL") 
03. // 取得したnameArrayListの件数文ループする
04. for (int i = 0; i < nameArraysList.size(); i++) {
05.     String[] nameArray = nameArrayList.get(i);
06.     int idx = 1;
07.     // nameArrayの配列数分繰り返す
08.     while (idx < nameArray.size) {

            // メインの処理を複数行に渡り記述

x1.         idx = idx + 3;
x2.     }
x3. }

最初に触れた「分かりきったことをいちいちコメントに書くな」と言いたくなる悪いコメント例です。コメントに記載した内容は、処理の意図ではなく処理そのものを日本語化したもの。一文読めば理解できることなので、これでは「分かりきったこと」と言いたくなっても仕方ありません。
こういうコメントもしばしば見受けられる珍しいものではないので、注意が必要ですね。

今回はここまでといたします。

今回のまとめ

• ３秒以内に処理の意図が読み取れないプログラムにはコメントを書く

• コメントには処理の意図を主体に書く

• プログラムの日本語訳のようなコメントは書かない