※このホームページは、バリアフリーを目指し、音声読み上げソフトに対応しています。

 


新・電子ノートブック Snap Note 3
  フリーソフト Snap Note 3 mini 公開!  

ソフトウェア・デザイン館 Sage Plaisir 21 へようこそ!
隔週月曜更新 : 毎週1つのニュースまたはプログラミング技術を取り上げ、解説します。

東日本大震災 まとめページ

[PR] 最強のスクリプト・ライブラリ vbslib5 が Windows 10 に対応!
[PR] シェル・スクリプトを格段に使いやすくする bashlib1 公開中


週刊 IT プログラミング技術 2018/11/ 5

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

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

a. 行の中にある一部のセルを入力して、同じ行の一部のセルに出力する(各要素の処理)
b. 複数の行の中にある一部のセルを入力して、別の表(複数の行)に出力する(複数検索)
c. 複数の行の中にある一部のセルを入力して、別の表の1行に出力する(単一検索)
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 - 説明変数

Sage Plaisir 21 のブログやツイッターを読もう!

Sage Plaisir 21 では、ここのホームページのほかにブログとツイッター も行っています。
ブログは、こちら。
ツイッターは、こちら。

Sage Plaisir 21 メールマガジンを読もう!

週刊 IT ニュース&コラム』には、 このページに掲載している コラムの他に、注目ニュースを集めたリンク集も、掲載しています。 日々多く集まる IT 情報から、注目すべき話題をコラム形式で取り上げますので、 ぜひチェックしておきましょう。 (サンプル、および登録)


Sage Plaisir 21 Contents
[ English | 日本語 ]

自動化ツールのダウンロード (2017-01-04) update!

急速な IT 革命により開発スピードの向上が課題になっています。 その鍵になるのがツールの活用または開発です。 一般的なものから専門的なものまで使えるツールを公開しています。

技術資料&オープンソース (2012-03-19)

扱う技術が多くなってくるにつれ、 技術はマスターするものではなく調べるものになり、 どれだけ実践に即した資料を集められるかどうかが、 勝負になります。標準的な技術の資料だけでなく、 プログラムソースやライセンスフリーのライブラリも公開しています。

オブジェクト指向プログラミング設計 (2000-04-01)

Visual Basic 7 にもついに本格的なオブジェクト指向の 機能が追加され、ソフトウェア技術者には必須の知識に なりつつあります。長年の研究の成果から、最新の応用方法まで 様々なメモを公開しています。

ソフトウェア・デザイン館より(技術エッセイ)   (2000-11-01)

プロの経験を通じて習得したソフトウェア全般に関する 技術を解説しています。 ソフトウェアとは何かといった根本的なことを通じて、 デザインに関するポイントをわかりやすく説明しています。


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

Simple and Visual

SagePlaisir21サーチ
パワード・バイ・グーグル

週刊 IT ニュース&コラム

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

10/22 Windows を最新版に更新するとファイルが削除される不具合

10/8 名前付き引数が使えないときの説明引数 - リーダブル コード(54)

9/24 Amazon スマートスピーカーの対応機器を増やす Alexa Gadgets Toolkit

9/10 関数の引数は入力と出力だけじゃない - リーダブル コード(53)

8/27 第三者が作成した電子書籍から作者へ利益還元するシステム

8/13 ワイルドカードを拡張する サブ フォルダー記号と FF-path 属性

7/30 CPU のリターン予測機能に見つかった脆弱性 スペクターRSB

7/16 メンバー変数は、グローバルのスタイルにする - リーダブル コード(52)

7/2 車のキーがスマホに置き換わる Digital Key

6/18 関数の引数は、グローバルとローカルの両方のスタイルにする - リーダブル コード(51)

6/4 EUの個人データ保護法GDPRの施行が開始され早速訴えられる

5/21 グローバルかローカルかを瞬時に分かるようにする - リーダブル コード(50)

5/ 7 漫画の海賊版サイトをブロッキングできるよう政府が体制整備

4/23 if節と主節を逆にするな - リーダブル コード(49)

4/ 9 Facebook で入手した個人情報がトランプ氏を当選させたとして炎上

3/26 カバレッジ100%を目標にしないほうが品質が高い

3/12 グーグルがよしとする Web ページかどうかを自動診断する Lighthouse

2/26 正常条件を示す、括弧の内側の空白を消すな - リーダブル コード(48)

2/12 コインチェックから NEM が流出、仮想通貨全体の信用低下

1/29 テスト プログラムに必須のコメント

1/15 CPU の投機実行とキャッシュに見つかった脆弱性 スペクターとメルトダウン

12/18 メモリーやコンピューターなど、語尾の長音記号を省略するな

12/4 ツイッターが認証済みアカウントの定義を変更

11/20 関数の直後に空白を入れるな - リーダブル コード(47)

11/4 無線LANの暗号 WPA2 に脆弱性 KRACKs、ただし危険度は小

10/23 XML にローカル変数が使えるようになる vbslib の LoadLocalVariableInXML

10/9 スマート スピーカー Google Home が日本で発売

9/25 XML に変数が使えるようになる vbslib の LazyDictionaryClass

9/11 京セラが汎用的な IoTユニットを開発。屋外での監視作業を自動化へ

8/28 変数の展開を遅延評価する vbslib の LazyDictionaryClass

8/14 HTML5 版ゲームのサービス開始や会社の設立が相次ぐ

7/31 人が死んだバグ、セラック25の事故から学ぶべき Nancy 教授の教訓

7/17 チケットの転売対策にも普及したSMS認証とその闇

7/3 Keyword Substitution の違いを無視して比較する DiffWithoutKS

6/19 安心して手軽にボランティア活動ができる &HAND

6/5 使っていないソースのセクションをカットする DoTextShrink

5/22 ツイッターの機能にフォーラムの機能を追加したマストドン

5/8 ソース ファイルの一部を隠す CutSharpIf, CutComment

4/24 iOS アプリ版ツイッターだけが17歳未満で使用禁止になる

4/10 マージがコンフリクトしても自動解決する ThreeWayMerge

3/27 あなたの机や壁がタッチパネルになる Xperia Touch

3/13 ソース ファイルの英訳と WHITE SQUARE エンコーディング判定法

2/27 運送業大手 UPS がトラックからドローンを発着する実験に成功

2/13 使いなれた外部プログラムを vbslib から起動する Setting コマンド

1/30 Nintendo Switch の新しいコントローラー Joy-Con

1/16 プログラム ソースの静的設定を一度に行う vbslib の Switches

12/19 銀行の API 仕様の公開へ、金融制度ワーキング グループ

12/5 よく使うコードの断片として登録するべきデバッグ用スニペット

11/21 ファンクション キーを Touch Bar に置き換えた MacBook Pro

11/7 人工知能の進化にみる論理的思考の限界と新しい開発プロセスの必要性

10/24 アマゾンが講談社の電子書籍を無断で配信を停止

10/10 レアケースの処理が最初に来る条件式を書くな - リーダブルコード(46)

9/26 東京ゲームショウ2016、PS4, PSVR 対応ゲームが本格化

9/12 数字があれば詳細に分析できているとは限らない

8/29 乾電池が IoT になる MaBeee が一般販売を開始

8/15 バカにはできない定性的な見積もりの代表 KKD 法

8/ 1 スマホ向けゲーム、ポケモンGOのダウンロードが開始され社会現象に

7/18 メインの処理の前の空行を詰めるな - リーダブルコード(45)

7/ 4 Webサービスを連携する IFTTT のイントラネット版、Microsoft Flow

6/20 名前空間のエイリアスは省略するな - リーダブルコード(44)

6/ 6 それぞれの工程に専門家を配置する工程別分業開発

5/23 それぞれの工程に専門家を配置する工程別分業開発

5/ 8 人間の手をスマート ウォッチのタッチパッドにする SkinTrack

4/25 テスト駆動開発では、失敗するようなテストを書くな

4/11 Windows で bash が動く Windows Subsystem for Linux 発表

3/28 手戻りの少ない仕様には、必ずテスト コードが存在する

3/14 連邦裁判所が命じた捜査協力を拒否するIT業界が隠していること

2/29 哲学の成果に基づいて、仕様書と同時にサンプルやテストを作ろう

2/15 Visual Studio Code がスマホ向けライブラリー Cordva に対応

2/ 1 ウォーターフォールは最後だけで、まずプロトタイピングをしよう

1/18 たった 5ドルのコンピューター Raspberry Pi Zero が発売

12/28 ルールをルールにするな - リーダブル・コード(43) 特別編

12/14 IBM、人工知能で適切な Web API を提案する API Harmony を発表

11/30 ヨーダ記法で書くな (4) - リーダブル・コード(42)

11/16 Android のアドウェアが2万を超えるアプリで検出される

11/ 2 ヨーダ記法で書くな (3) - リーダブル・コード(41)

10/19 フォルクスワーゲンが排出ガス処理の無効化プログラムを認める

10/ 5 ヨーダ記法で書くな (2) - リーダブル・コード(40)

9/21 3D Touch の iPhone 6s、大画面の iPad Pro を発表

9/ 7 ヨーダ記法で書くな (1) - リーダブル・コード(39)

8/24 Windows10 のオンライン無料アップグレード開始。無料期間は1年

8/10 ポインター宣言を表す * を変数に付けるな - リーダブル・コード(38)

7/26 Nintendo DS, Wii を開発した 任天堂の岩田聡社長がご逝去

7/13 カッコの内側の空白の有無を統一するな - リーダブル・コード(37)

6/29 日本年金機構から個人情報流出。対策法の改善を考察する

6/15 連続した空白を1つにまとめるな - リーダブル・コード(36)

6/ 1 iOS や Android 向けのソースもビルドできる Windows 10

5/18 インクリメントの演算子を書くな - リーダブル・コード(35)

5/ 4 Apple Watch 発売。スマホが普及した現代に必要かどうか

4/20 大文字小文字に統一するな - リーダブル・コード(34)

4/ 6 Google の次世代 JavaScript、Dart は Chrome に組み込まない方針へ

3/23 配列を pointer と名付けるな - リーダブル・コード(33)

3/ 9 Lenovo 製 PC に付属の Superfish に Web サイトを偽装する脆弱性

2/23 ハンガリアン記法を使うな - リーダブル・コード(32)

2/ 9 現実世界にホログラムを表示することが現実的になる HoloLens

1/26 this ポインターを省略するな - リーダブル・コード(31)

1/12 新型 MacBook Air は、USB Type-C 端子のみ搭載されると予想

12/22 キャピタライゼーションを無視したルールを作るな - リーダブル・コード(30)

12/ 8 Visual Studio Professional と同じ機能の無料版 VS Comminuty

11/24 性能を暗黙的に示すルールを作るな - リーダブル・コード(29)

11/10 W3C より HTML 5 がついに勧告される

10/27 実装依存回避のために独自の定義をするな - リーダブル・コード(28)

10/13 多くの Linux で使われる bash に重大な脆弱性が多数発生

9/29 #define のシンボルを大文字だけにするな - リーダブル・コード(27)

9/15 富士通が発表した設計書からプログラムを自動生成するツールの使い道

9/1 連続した空行、空白、アンダースコアを禁止にするな - リーダブル・コード(26)

8/18 YouTube のような無料の PDF 文書投稿サイト PDFy

8/4 処理内容を示していない関数名を禁止にするな - リーダブル・コード(25)

7/21 Facebook がニュースフィードの一部を減らして無断で心理実験

7/7 プリプロセッサーを行頭に書くな - リーダブル・コード(24)

6/23 Google が YouTube からインディーズレーベルを締め出し

6/9 計算順序を明示する冗長な括弧は書くな - リーダブル・コード(23)

5/26 Google と OpenSSL にパスワードなどが盗み取られる脆弱性

5/12 アドレスに &演算子を強制するな(2) - リーダブル・コード(22)

4/28 STAP 細胞の疑惑を最初に指摘した匿名検証サイト PubPeer

4/14 アドレスに &演算子を強制するな(1) - リーダブル・コード(21)

3/31 マイクロソフトの Office 365 が iPad に対応、閲覧は無料

3/17 アドレスやポインターを配列にするな - リーダブル・コード(20)

3/3 仮想通貨 ビットコイン の大手取引所 Mt.Gox が民事再生法を申請

2/17 カード節と分岐を一緒にするな - リーダブル・コード(19)

2/3 Google Chrome から CSS Regions 標準のサポートを廃止する検討

1/20 複雑な条件式は AND と OR だけにするな - リーダブル・コード(18)

もっと前の記事

自動化ツールのダウンロード

Snap Note 3 mini - サクサク使える自由ノート  new!

Plastic Window 1.20 - ウィンドウを半透明に  new!

Shortcut Director 1.00 - ショートカットのリンク切れ修正

Archives Folderizer SV 1.10 - 圧縮解凍

デジタルスクラップブックSVG Cats 2

その他のツール

オブジェクト指向プログラミング設計

技術資料

All Text composed by T's-Neko ts-neko@sage-p.com,