IT ニュース＆コラム    2018/11/ 5   通巻775号  技術版

                             ソフトウェアデザイン館  Sage Plaisir 21

￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣


■■　変数を設定するためのループに付けるコメント - リーダブル コード(55)　■■


構造化定理（構造化プログラミングではない）における「反復」（ループ）は、
主に集合に対する処理で使われます。 もう少し詳細なレベルで反復処理を分類してみましょう。 
分かりやすくするために、表の行とセルで説明します。
集合は表、集合の要素は行、要素を構成する変数がセルです。

a. 行の中にある一部のセルを入力して、同じ行の一部のセルに出力する（各要素の処理）
b. 複数の行の中にある一部のセルを入力して、別の表（複数の行）に出力する（複数検索）
c. 複数の行の中にある一部のセルを入力して、別の表の１行に出力する（単一検索）
d. 複数の行の中にある一部のセルを入力して、別の表のセルに出力する（合計など表の変数）
（他にもありますが、ここでは省略します）

今回は、c のタイプの反復処理に対するコメントの付けかたの話です。 
と言っても以上の説明を理解するのは難しいので、C言語で表してみます。

for ( i = 0;  i < _countof( array );  i += 1 ) {
    if ( array[i].State == c_stop ) {
        break;
    }
}

ちなみに、変数定義は、以下のようになります。

struct StructA  array[10];
int  i;
static const int  c_stop = 2;

あなたなら、この反復処理が全体で何をしている処理であるとコメントを書きますか？

配列 array のうち、State メンバー変数の値が c_stop である要素が
どれであるかを線形検索していますね。
コメントを書くなら次のようになるでしょうか。

/* 停止状態である要素を検索する */

しかし、このコメントは、抽象的すぎるという問題があります。
「要素」とは何を指しているのでしょうか、
「停止状態」とは何を指しているのでしょうか。 

ブロックごとに適切なコメントを書くというコーディング ルールを作っても、
このような役に立たないコメントを書いたところで何も良くなりません。
無駄なルールです。
ルールに従っているからきっと良いことがあるだろうと根拠もなく信じているだけです。
（逆に、コードを書かないでルールを信じて監視する人が無駄な指摘してしまうことを
回避するために、適当に書いて信じこませましょう。）

このコメントでも、読めばコメント自体を理解することはできるでしょう。
しかし、コードを理解したことにはなりません。 なぜなら、正しさを検証したり
問題を見つけたりするために必要な理解までできていないからです。
それができるには、コメントとコードの対応関係を踏まえなければなりません。

コメントとコードの対応関係を示すには、コードで使われているシンボルをコメントの中に
入れるしかありません。 

/* 停止状態 c_stop である要素 array[i] を検索する */
for ( i = 0;  i < _countof( array );  i += 1 ) {
    if ( array[i].State == c_stop ) {
        break;
    }
}

更に、コードの中の変数を説明変数に変更することで、コメントがシンプルになり、
理解もしやすくなります。 最終的には次のようになります。

1: /* stop_array_index = ... */
2: stop_array_index = -1;
3: for ( array_index = 0;  array_index < _countof( array );  array_index += 1 ) {
4:     if ( array[ array_index ].State == c_stop ) {
5:
6:         stop_array_index = array_index;
7:         break;
8:     }
9: }

一見、不親切なコメントに見えるかもしれません。 変数 stop_array_index に何かを
代入している、ということしか書いていないですから。 しかし、この書き方こそ
理解がしやすく理解が早い順序でコードを読むことができる仕掛けなのです。

以下の説明では、上記のコードをテキスト エディターにコピーして検索しながら
読むと、ここで言いたいことが伝わると思います。 最近のテキスト エディターは、
シンボルを検索したときに、ヒットしたすべての部分を強調表示してくれるので、
それを活用しない手はありません。

コメント（1行目）に書かれている stop_array_index を検索すると、
（6行目）stop_array_index = array_index; がヒットします。
続いて右辺の array_index を検索すると、（4行目）if 文と（3行目）for 文がヒットします。
このように理解していくわけですが、その理解の順序は、ツリー構造のトップ ダウンで
理解する順序（概要から詳細の順序）なので、理解がしやすく理解が早いのです。
ボトムアップでは、読んだ後にすでに知っていることだと思うことがあり、遅くなります。

よって、このタイプのループは、変数を設定することが目的のループであるので、
その設定を行う変数の名前を明示することが重要であり、それだけでも十分なのです。

「検索」という言葉がコメントにあったほうが理解しやすいと思うかもしれませんが、
それは手段の説明にすぎないので、あまり役に立ちません。 目的は、「停止状態である要素」
を求めることです。 もちろん「検索」がコメントにあれば検索の処理をしていることが
すぐに理解できるのですが、その理解は必要ではないことが多いです。
もし、停止状態の要素を表示させたいのに、停止状態ではない要素が表示された不具合が
あった場面を考えてください。 それを解決するのであれば、このブロックに不具合が
あるだろうと注目する範囲を素早く狭めることと、その条件式をコードで確認することが
必要なのであって、検索であることを知る必要はないのです。

また、上から順に読んでいくと、変数名は、array_index より i のほうが理解しやすいと
思うでしょう。 私もそう思います。 しかし、それは、i がループ変数であることが
理解できただけで、i が何に対する配列番号であるかを理解したことにはなりません。
理解するには、array[i] の部分を読まなければなりません。
上から順に読んでいくと、上記のようにトップ ダウンで理解することにはなりません。

また、ループの内容が大きくなると、i が何だったか忘れたか、for 文をまだ読んで
いなかったときは、i の定義をまた探さなければなりません。 もし、i が array_index 
という名前なら、その名前から理解できるのです。 array_index の定義を探す行為は、
その意味が間違いないことをダブル チェックで確認する行為です。 i だけでは
ダブル チェックにはなりません。 説明変数は非常に重要です。

ソース
https://ja.wikipedia.org/wiki/構造化プログラミング
https://ja.wikipedia.org/wiki/構造化定理
http://blog.livedoor.jp/sage_p/archives/51916281.html - 説明変数



■■　注目ニュース  一覧　■■

◇ 新 MacBook Air、Mac mini、iPad Pro 登場、アップル発表総ざらい。
https://japan.cnet.com/article/35127866/
 … iPad に USB Type-C、Mac Book Air に Retina ディスプレイとユーザーの期待に応える。

◇ Nintendo SwitchをVRゴーグル化する NS Glasses。Switchを3Dにスイッチ。
https://japan.cnet.com/article/35127420/
 … Switch のコントローラーとの相性もよさそう。

◇ IBM、レッドハット買収で合意。3.8兆円。
https://japan.cnet.com/article/35127693/
 … オープンなクラウドソリューションという矛盾したキーワード。

◇ グーグル、ブラウザのURL欄に doc.new と入力するだけで新規文書を作成可能に。
https://japan.cnet.com/article/35127709/
 … ただし、google にログインした状態であること。

◇ グーグル、画像内に写ったものをAIが特定する Google Lens。画像検索で利用可能に。
https://japan.cnet.com/article/35127723/
 … 写真に写ったこのおしゃれな家具を特定可能になる。プライバシーの問題も再燃するか。

◇ グーグル、reCAPTCHA に新バージョン。操作不要で人間であると証明可能に。
https://japan.cnet.com/article/35127820/
 … 複数のページにまたがるユーザーの操作から総合的に不正ロボットではないかを判断。

◇ Cygames、技術開発子会社 Cysharp を設立。C#の専門集団。
https://japan.cnet.com/article/35127988/
 … 自動化に必須の言語を扱える人が集まることで、エクセル職人が非難されるような文化にならない。

◇ アップルやグーグルなど数十社、トランプ政権のトランスジェンダー排除の方針を非難。
https://japan.cnet.com/article/35128027/
 … トランスジェンダーの人々は、他のマイノリティを味方につけた方がいい。

◇ NYTにセクハラを報じられたアルファベット傘下 X の上級幹部が退職。
https://japan.cnet.com/article/35127923/
 … IT業界には、さまざまなレベルのセクハラが横行しているらしい。

◇ ウェブの父バーナーズ・リー氏、データを企業から個人の手に取り戻す新計画。
https://japan.cnet.com/article/35126325/
 … 個人データの書き込み、読み込み、アクセス管理を行える Solid。

◇ Alexa for Business、サードパーティーのデバイスに組み込み可能に。
https://japan.cnet.com/article/35127636/
 … スマート スピーカーを他の家電の１つの機能に。

◇ カリフォルニア州でIoTセキュリティ法。
https://japan.cnet.com/article/35126328/
 … スマート スピーカーの影響か。

◇ Google News アプリが膨大なデータ通信量を消費、多数ユーザーが報告。
https://japan.cnet.com/article/35127473/
 … スマホのシステムに１日の使用量を監視する機能がほしい。

◇ 世界初の折りたたみスマホ FlexPai、中国メーカーのRoyoleから登場。
https://japan.cnet.com/article/35128045/
 … 新製品はベンチャーがやりやすいのだが、その品質はどうか。

◇ 中国のNubia、表裏デュアル画面のフラッグシップスマホ Nubia X を発表。
https://japan.cnet.com/article/35127953/
 … ノッチ（iPhoneX の上部）もない。



■■　ソフトウェアデザイン館  Sage Plaisir 21　■■


  ホームページ   >>> http://www.sage-p.com/
  メルマガ       >>> http://www.mag2.com/m/0000083983.html
  ブログ         >>> http://blog.livedoor.jp/sage_p/
  ツイッター     >>> http://twitter.com/Ts_Neko
  ダウンロード   >>> http://www.sage-p.com/freesoft.htm
  サポート掲示板 >>> http://www.sage-p.com/kg_ban09/z6037C8.cgi
  東日本大震災   >>> http://www.sage-p.com/saigai.html
  メール         >>> ts-neko◇sage-p.com   ←◇を@に変えてください
                     緊急メールは件名に「うどんメール」を付けてください。

      このメルマガの登録・解除 - http://www.mag2.com/m/0000083983.htm