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

 


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

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

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

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


週刊 IT プログラミング技術 2018/12/31

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

コメントを書くことで詳しく説明できるのは当然、人間なんだから自然言語で
書かれた説明のほうがコードを読むよりも理解しやすいのは当然、と考える人が
コードを書かない人に多いのですが、その考えは常識でもなんでもなく、むしろ逆です。

プログラムのソースコードに書く関数名や変数名は、英単語を省略しないように
するだけでも、かなり読みやすくなります。 たとえば、stat と省略しないで、
status ときちんと書くことです。 それだけで、正しい単語に変換する人間の
思考回路の動作が省略できますし、誤った単語を覚えてしまわないようになります。

そして、適切な関数名を付ければ、関数に対するコメントも必要なくなります。 
コメントが必須となるコーディング・ルールの元で、コメントを書くと、
関数名と同じ説明文になることから、コメントが必要ないことが体験できます。

開発中のコードは略語でも理解できるから問題なく、むしろ略語のほうが文字数が
少なくて読みやすいことは実感しますが、略語が他の人や未来の自分が読めない
コードの原因になっていることまで理解しておらず、その結果、略語で書かれた
読めないコードが氾濫しています。 そのため、コードは読めないものだという
誤った常識が形成され、コードは読めないものだからコメントを書かないと読めない
と考えるようになってしまっています。しかし、そもそも略語を禁止して読める
コードにすればいいのです。

自然言語は曖昧であるため、自然言語(ワード)とコードの対応関係が必要になり、
それが書かれていないと、コメントが書いてないコードよりももっと混乱する
ことになります。 また、自然言語のワードとコードの対応関係の正しさの検証も
必要になりますし、自然言語のコメントの対象としたコードのバージョン管理も
必要になります。 自然言語では表記ゆれが発生しますし、ワードの意味が未定義
のままになることもあります。

ですので、コメントが必要なら、必要最低限にしなければなりません。 
最も効率よくコードの理解を助けるコメントがどういうものか、
その研究結果をシンプルコメント2としてまとめました。


■ 関数名() のシンプルコメント

コメントより関数名のほうが、多くの人にレビューされて洗練されたフレーズに
なります。 関数を呼び出すときに関数名のコピーが書かれて見ることになる
からです。1文字でも違うとエラーになります。

ただ、コメントが全く不要というわけではありません。 どうしても必要な
コメントがあります。それは、関数の中の複数行のコードが意味のある
センテンスになるとき、そのセンテンスの最初に書くコメントです。

それは、一般的に知られているブロック(センテンス)を開始するところに書くコメントです。 

 /* XML を解析します */  config.Flags =    F_ParseXML2_Delegate |    F_ParseXML2_OnStartElement;  config.Delegate = work;  config.OnStartElement = MkkwdsWorkClass_makeInFile_onXML_StartElement;  e= ParseXML2( path, &config ); if(e){goto fin;}
上記のコメントは、その下の6行で行うソースコード内容を説明しています。 このセンテンスに対するコメントを省略すると、ソースコードを読む速度が 下がります。 なぜなら、コメントが無いときは、たとえ全部でなくても、 ソースコードを上から読んでいく必要があるからです。 そして、上記のコメントを更に洗練させたのが、関数名() のシンプルコメント2です。
 /* ParseXML2() */  config.Flags =    F_ParseXML2_Delegate |    F_ParseXML2_OnStartElement;  config.Delegate = work;  config.OnStartElement = MkkwdsWorkClass_makeInFile_onXML_StartElement;  e= ParseXML2( path, &config ); if(e){goto fin;}
コメントには関数名をそのまま書き、() を付けます。 前のバージョンのシンプルコメントでは、Call "ParseXML2" と書いていましたが、 Call を書くと Call という単語が頭に入って混乱してしまう欠点がありました。 BASIC 言語で Call を書かなくなったことと同じ理由です。 () を書くことでその混乱が起きなくなると同時に、() の前が関数名であることが 分かります。 () の前が関数名であることは、ほとんどのプログラミング言語の 文法として採用されていて、命名規則の説明文でそれが関数名であることを 説明するまでもないため、ルールがシンプルになります。 もし、コメントを自然言語で書くと、関数名による説明とコメントによる説明の 2つの視点からの説明を受けることになります。 これは、知っている単語に ついて毎回別の表現で言われることになるため混乱します。 たとえば、 「printf します。」で済むことを、「コマンド プロンプトに出力します。 つまり、printf します。」と言われているようなことです。 脳内では printf というワードで処理内容をチャンキングして理解しているのに、 チャンキングをばらした意味から読むことになるので、非効率なのです。 人によっては、違った概念でチャンキングが構成されていることもあり、 その場合はコメントの内容を疑い始めることになり非効率です。 関数名はシンボルなので、シンボルから説明書を検索することができ、 詳細を知ることもできるようになります。 関数を呼び出す側のコメントは、 あまり洗練されていませんが、関数の説明書に書かれた文章は、何度も読み返されて 洗練された文章になっていて、理解も早いです。 人によっては、関数の仕様を 自分が最も理解しやすい表現で説明したメモを持っており、そちらを読み返した 方が理解が早いです。 関数名とコードだけでは説明が不十分なときは、関数名() : 説明、という コメントにします。 説明には、なるべく変数名や関数名を含めるようにします。
 /* ParseXML2() : "in_TemplatePath" が指すファイルの XML を解析する */
関数を呼び出していないときや、呼び出している関数名が適切でないとき、 かつ、後述する 変数名 = ... のシンプルコメントが使えないときに限り、 自然言語でコメントを書きます。 また、リーダブル コード(56)で、空行をブロックの前ではなく読ませたい 文の前に入れることで、重要な文を読ませることが自然にできることを説明 しましたが、通常、シンプルコメントに書いた関数を呼び出す文が、読ませたい 文になるため、その直前に空行を入れます。 ■ 変数名 = ... のシンプルコメント 処理内容(関数名)の理解の次に重要なのが、その処理対象(引数や入力変数名) となるデータの理解です。 既存の変数やリテラルを引数にそのまま渡すときは、 コメントがなくてもコードから読めますが、関数の前半で行う処理の出力を 引数に渡すときは、前半の処理の出力データの説明が必要になります。 前半で行う処理のうち注目すべき出力変数(通常、引数に渡す変数)に関わる 処理をまとめたセンテンス作り、それが開始するところに、 変数名 = ... のシンプルコメントを書きます。 ... はコードの内容を指しています。
 /* path_written_in_other_XML = ... */  GetApplicationStatus( &status ); /* status = . */  e= ParseXML2_StatusClass_getAttribute(    status, _T("path"), &path_written_in_other_XML ); if(e){goto fin;}  /* ParseXML2() */  config.Flags =    F_ParseXML2_Delegate |    F_ParseXML2_OnStartElement;  config.Delegate = work;  config.OnStartElement = MkkwdsWorkClass_makeInFile_onXML_StartElement;  e= ParseXML2( path_written_in_other_XML, &config ); if(e){goto fin;}
path_written_in_other_XML 変数は、ParseXML2 関数の引数に渡す値の説明変数です。 リーダブル コード(57)で、空行の後に説明変数を積極的に使うことで、 重要な文を英文として読めるようになり、理解しやすくなることを説明しましたが、 変数名が長いのはそのためです。 説明変数は自然言語に近いため詳細で厳密な定義を知りたくなることがあります。 変数名 = ... のシンプルコメントが書いてあると、その定義を知ることができる 場所がすぐに分かります。 説明変数を return 文に渡すことで、返り値の説明もできます。 ただし、Get 関数では、関数の説明書に書かれた洗練された文章のほうが 適切かもしれません。
 /* path_written_in_other_XML = ... */  GetApplicationStatus( &status ); /* status = . */  e= ParseXML2_StatusClass_getAttribute(    status, _T("path"), &path_written_in_other_XML ); if(e){goto fin;}  return path_written_in_other_XML;
引数で出力する関数を呼び出したときは、関数呼び出しの後に、 出力変数 = . のコメントを書きます。 上記では、status = . の部分です。 . は同じ行または前の行の文を指しています。 このコメントがあることで、変数の値が変化することが一目瞭然になります。 また、変数の詳細で厳密な定義を知りたいときに "変数名 =" で検索することが できるようになります。 もしこのコメントがなければ、関数の引数が出力引数であることを覚えておくか 関数の仕様書を見るか、実際に動作させなければ、変数の値が変化することが 分からなくなり、コードを理解する効率が非常に悪くなります。
 GetApplicationStatus( &status ); /* status = . */
(次回に続きます) 参考
>>> 空行はブロックの前ではなく読ませたい文の前に入れる - リーダブル コード(56) >>> 空行の後は説明変数を積極的に使うこと - リーダブル コード(57)

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

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,