IT ニュース＆コラム    2019/ 3/11   通巻783号  技術版

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

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


■■　ソースコードが早く読めるようになる、シンプルコメント２ - リーダブル コード(59)　■■


前回は、主な処理を行う関数名() のシンプルコメントと、注目すべき出力変数 = ... の
シンプルコメントを説明しました。今回はその続きです。


■ (variables) = ... のシンプルコメント

　/* (variables) = ... */
　const int　length_of_MD5 = 32;
　char*　　　string_A = malloc( length_of_MD5 + 1 );
　char*　　　string_B = malloc( length_of_MD5 + 1 );
　string_A[0] = '\0';
　string_B[0] = '\0';

(variables) = ... のシンプルコメントは、概要を知るときに、最初に読んで内容を
理解する必要がない「雑多な変数への代入」の文を集めたブロックの先頭に書きます。
このブロックには、基本的に空行を入れないようにします。

最初に読むときは、(variables) = ... のブロックは、読み飛ばします。
下のほうのブロックで、内容を知りたくなった変数の名前で検索したときに、
(variables) = ... のブロックの中の１つの代入文が見つかったら、その代入文だけ
読みます。 (variables) = ... のブロック全体を読むことはありません。

一般の文書は、まず概要が書かれており、続いて内容や詳細が書かれています（概要→内容）。
その順序のほうが理解しやすいからです。 しかし、関数定義のコードは、まず内容が書かれ、
続いて概要が書かれているようにどうしてもなってしまいます（内容→概要）。 なぜなら、
処理順序の都合により、関数定義の下のほうに主な処理を行う関数の呼び出しが書かれ、
関数定義の上のほうには、その主な処理を実行するために必要なデータを集める処理が
書かざるを得ないからです。

空行を入れないようにする理由は、コードを読む人が、空行の次の行を読もうとしてしまう
ことを防ぐためです。（参考：リーダブル コード(56)） 雑多な変数への代入において、
どれが注目すべき重要な代入であるかは無いからです。 もし注目すべき重要な代入が
存在したら、注目すべき出力変数 = ... のシンプルコメントのブロックに書くからです。

関数定義の先頭では、(variables) = ... のシンプルコメントを省略しても構いません。
最初に関数定義の内容を読むときは、コメントが書かれている部分を先に読む
可能性が高く、それは関数定義の先頭のブロックを読み飛ばすことになり、それは 
(variables) = ... のシンプルコメントの目的と同じだからです。


■ Guard のシンプルコメント

　/* Guard */
　e= ReadCondition( &condition ); if(e){goto fin;}
　if ( !( condition != NULL )) { e=E_OTHER; goto fin; }

Guard のシンプルコメントは、ガード節と呼ばれているブロックの先頭に付けるコメント
です。 エラーチェックや事前条件チェックなど、正常に処理が完了したときに不要となる
処理であることを表します。 いわゆる異常系の処理です。 異常系の処理は、処理の概要を
知るときには、必要のない情報です。

最初に読むときは、Guard のシンプルコメントのブロックを読み飛ばします。
最初でなくても、正常系の処理を読んでいるときも、Guard のシンプルコメントの
ブロックを読み飛ばします。


■ ... のシンプルコメント

　/* ... */
　count = 0;
　fclose( file );
　DeleteFile( temporary_file_path );

その他の処理、説明が難しいブロック、説明することに効果がないブロックなどを
開始するところに書くコメントです。 コメントの内容は ... です。 情報がゼロかと
思うかもしれませんが、このコメントには、前のブロックが終了したという情報があります。

すべてのコメントを分かりやすく書くことは総論としては正しいですが、ときには
理想論になります。 あまり重要でないコードに対して分かりやすい説明を書く時間を
さくぐらいなら、他の作業を優先すべきです。


■ Set up, Test Main, Check, Clean のシンプルコメント

/* Set up */
:

/* Test Main */
:

/* Check */
:

/* Clean */
:

テスト プログラムに書くべき必須のコメントは、以下のとおりです。 

・準備（Set up）
・テスト対象の実行（Test Main）
・期待した出力と合っているかチェック（Check）
・クリーン（Clean）

詳しくは、本連載の 755号「テスト プログラムに必須のコメントのフォーマット」
を参照してください。


■ Cases are ... のシンプルコメント

/* Check : "is_same" */
/* Cases are "input_path", "answer_path", "is_deleted" */

Cases are ... のシンプル・コメントには、テストケースの値を格納する
変数を書きます。

テストでは、テストの内容が重要ですが、それだけでなくテストケースが
十分網羅されているかを読めることが重要です。 テスト関数を一覧することで
網羅されているかを読むことは難しいです。 関数一覧だけでは足りません。
多くはループ変数などに代入する値を一覧することで十分網羅されているか
を確認することができます。

また、テスト プログラムは、ループをよく使い、コード自体は多くのケースが
総合されたコードになる傾向があります。 最初のテスト プログラムは簡単だった
のに、現在は複雑になってしまったということがよくあると思います。
簡単なケースだけ、別のコードにするテクニックもありますが、すべてのケースで
別のコードにするわけにもいきません。 そういったときに、テストケースの値と、
その値を格納する変数を最初に踏まえることで、テスト プログラムのコードが
読みやすくなります。

参考：
シンプルコメント２（前半）
http://blog.livedoor.jp/sage_p/archives/52085546.html

テスト プログラムに必須のコメントのフォーマット
http://blog.livedoor.jp/sage_p/archives/52061883.html



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

◇ 3Dモデルを立体視できる透明な箱 Looking Glass が日本上陸。
https://www.itmedia.co.jp/news/articles/1902/26/news058.html
 … 空中ではないが、透明な箱の中で立体視できる。これが最も現実的な裸眼3D表示になりそう。

◇ Nintendo Labo VR Kit が4月12日発売。Switchと段ボール製工作キットで楽しむVR。
https://japan.cnet.com/article/35133825/
 … 鳥の目になったりする。

◇ いたずらスクリプトのURL貼った女子中学生の補導、海外でも波紋。
https://japan.cnet.com/article/35133776/
 … 掲示板に偽の殺人予告を書いただけでも脅迫罪になることと同じ。

◇ マイクロソフト、HoloLens 2 発表。約39万円、視野角は2倍に。
https://japan.cnet.com/article/35133189/
 … 値段が高いのでプロ向け。

◇ 網膜レベルの超高精細なVR体験。プロ向け Varjo VR-1 試用レビュー。
https://japan.cnet.com/article/35133019/
 … VRゴーグルでも精細な表示ができることが技術的には可能。

◇ 雇用主が必要とするプログラミング言語。学生が学ぶ言語と乖離することも。
https://japan.zdnet.com/article/35133438/
 … 言語仕様が整理されていない JavaScript では体系的に学ぶことが難しい。

◇ 活動量計 Microsoft Band 向けサービスとアプリが終了へ。
https://japan.cnet.com/article/35133610/
 … フィットネス バンドの機能は出尽くして、Micosoft が入る余地は無くなったか。

◇ CA Tech Kids、奈良県の小学校でプログラミングの反転授業。オンライン教材の効果は？
https://japan.cnet.com/article/35133452/
 … ICTが向く科目なら導入すべき。



■■　ソフトウェアデザイン館  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