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

 


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

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

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

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


週刊 IT プログラミング技術 2019/ 3/11

ソースコードが早く読めるようになる、シンプルコメント2 - リーダブル コード(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) = ... のブロックの中の1つの代入文が見つかったら、その代入文だけ
読みます。 (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 ... のシンプル・コメントには、テストケースの値を格納する
変数を書きます。

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

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



参考
>>> シンプルコメント2(前半) >>> テスト プログラムに必須のコメントのフォーマット

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 ニュース&コラム

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

2/25 無料で使えるように改変した iOS アプリを何者かが配布

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

1/28 5月1日から変更される新元号の名前の発表が 4月1日に決定

12/31 空行の後は説明変数を積極的に使うこと - リーダブル コード(57)

12/17 グーグル Chrome のコアが、Microdoft Edge ブラウザーのコアに採用へ

12/3 空行はブロックの前ではなく読ませたい文の前に入れる - リーダブル コード(56)

11/19 Windows Update するとファイル名の大文字小文字を区別しないことが可能に

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,