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

 


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

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

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

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


2020年より、IT ニュース&コラムは 3週に1度の配信となります。 次回の配信は 2020/1/20です。

週刊 IT プログラミング技術 2020/ 1/20

コメントを書かずに概要を説明する方法 - リーダブル コード(61)

プログラムのソースコードにコメントを書かないのが最近の傾向としてあるようです。
たとえば、1行のコードをそのまま日本語訳したようなコメント(ライン コメント)。

  // docx ファイルを保存する
  docx.SaveAs( path_of_text_file )

これは明らかに不要ですね。 英語をそのまま日本語訳しただけですから。
英語が分からなければ翻訳サイトを見れば中学生でも分かります。
また、翻訳サイトがライバル会社ではないので漏えいしても問題ありません。

一方で理由をコメントに書くことは、ほとんどの人が必要と言っているようです。
コードを読むとき、関数のインターフェース仕様などを踏まえて推測しながら理解すると
思いますが、仕様から推測できないコードが書いてあると、理解に時間がかかりますし、
コード自体も疑わしくなるからでしょう。それで時間をかけたのに結局コードは変えなかった
としたら効率が悪いです。 

しかし、すべてのコードに理由のコメントを書く必要はありません。
仕様などから推測できるコードであれば、理由のコメントを書く必要はありません。
普通の会話と同じで、すべての会話に理由を言っている訳ではありません。
いちいち理由を言うと、相手にはバカにされていると思われるでしょうし。

理由のコメントは、コードと同じ行の右、もしくは次の行でインデントして書きます。
コメントはコードの常に前の行に書くべきだというルールを言う人もいますが、
主従関係を考えると先にコードがあって、後で理由を書くべきです。
メールで結論から書くのと同じ理由です。

  file.DeleteForce()  // 普通の Delete では削除できないことがあるため

  file.DeleteForce()
    // 普通の Delete では削除できないことがあるため

逆に、関数全体やプロパティに対するコメントが必須になってきている傾向があるようです。
コストを低くかつ検索やリンクができて便利なドキュメントを提供するために、
ソースコードのコメントからドキュメントに変換するツール、javadoc, NatrualDocs, 
doxgen などを使うことが普通になってきたからでしょう。

さて、ここからが本題です。関数定義の中の 2〜20行程度のコードの概要を説明する
コメント(ブロック コメント)をコードの前の行に書くことが、よくあると思います。 
数行のコードの概要を表現するためのコメントです。

  (前のブロック)

  // parameter で示したシート(エクセル ファイルのシート)を削除する
  dot_position = parameter.indexOf( "." )
  sheet_name   = parameter.substring( 0,  dot_position )
  cell_position = parameter.substring( dot_position + 2 )
  excel = GetExcelFile( excel_file_path )
  excel.Sheets( sheet_name ).Delete()

  xlsx.SaveAs( excel_file_path )

このようにコメントで概要を表現することはできたのですが、ブロックがいくつかある中で
1行しかないブロックもあり、バランスが悪いですね。 そのブロックにもライン コメントを
書けばバランスは良くなりますが、ライン コメントは否定されつつあります。
概要を書くことをルールにすればうまくいくわけではないのです。

そこで、概要のコメントを書きたくないとき、コメントを書かなくても理解できるコードに
変える(リファクタリングする)方法を紹介します。

上記のコードを改良したコードを示します。

  (前のブロック)

  excel = GetExcelFile( excel_file_path )
  deleting_target = parameter
  dot_position = deleting_target.indexOf( "." )
  sheet_name   = deleting_target.substring( 0,  dot_position )
  cell_position = parameter.substring( dot_position + 2 )

  excel.Sheets( sheet_name ).Delete()

  xlsx.SaveAs( excel_file_path )

このようにコードを変えるには、いくつかテクニックを使っています。 それは、
リーダブル コード(56) で説明した「空行はブロックの前ではなく読ませたい文の前に入れる」と、
リーダブル コード(58) で説明した「変数名 = ... のシンプルコメント」の応用、
第801号で説明した「Linuxによくある謎の記号による処理を説明変数で読みやすくする方法」です。

コードの移動

コードを変えるときに重要な指針は、概要に相当するコードを読ませることと、必要なら
概要に相当するコードに変えることです。 まず、

  excel = GetExcelFile( excel_file_path )

を先頭行に移動しました。 こうすることで、処理対象が excel_file_path 変数で
示したエクセル ファイルであることをコードを読む人は最初に知ります。 
ちなみに、元のコードでは、変数を定義するコードを参照するコードを近い位置にするという
方針に従っていますが、それが最優先にしたところで読みやすくはなりません。 もし、移動する
コードが概要のコードでなければ、その方針に従うのがよいですが、今回はそうではありません。

単純な代入文の追加

  deleting_target = parameter

を追加し、parameter 変数を参照しているコードを deleting_target に変えました。
処理的には何の計算や呼び出しもしていない単なる代入なので不要に思うかもしれませんが、
代入する変数名に概要を含めることができるのです。 こう書くことで、読む人は、削除対象が 
parameter であることを知ります。 ちなみに、このような単純な代入文は、変数を定義する
コードと参照するコードを近い位置にすることにも使えます。

次に代入するコードが続きますが、ブロックの概要を理解した気になった人の多くは、
次のブロックを読み始めるものなので、あまりブロックの中盤以降のコードにこだわる必要は
ありません。 また、概要を理解しなくても長いブロックになれば読みたくなくなるものです。 
そういう場所に、概要に該当しないコードを書きます。 

空行の追加

  excel.Sheets( sheet_name ).Delete()

の前に空行を追加しました。このコードは概要のコメントに書いたそのものに対応する
コードなので、読む人に読んでもらいたい。 だから空行を追加しました。

以上で、すべてのコードを読む前に、概要「parameter で示したシート(エクセル ファイルの
シート)を削除する」を知ることができるコードになりました。 読む人にとっては、
概要が書いていないのに不思議と理解できるコードという感覚になると思います。

システムの設計書がプログラムのソースコードになりつつあるので、今後は、コードを
読みやすくする技術は、読みやすく文章を書く技術と並んで重要になっていくでしょう。
いや、すでに現場ではそうなっています。

参考
・コードコメントの書き方で書き手のレベルが分かる!コメントにはWhyを残せ!良い?悪い?コードコメントの書き方
・リーダブルコード - より良いコードを書くためのシンプルで実践的なテクニック
 8.1章 説明変数、8.2章 要約変数

ソース
  >>>  https://www.itmedia.co.jp/news/articles/1912/26/news104.html
  >>>  https://www.microsoft.com/en-us/research/publication/spaceink-making-space-for-in-context-annotations/




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

1/20 コメントを書かずに概要を説明する方法 - リーダブル コード(61)

12/30 書くスペースを半自動的に作ってメモをしやすくする SpaceInk

12/16 手続き型プログラミングと宣言型プログラミングを使い分ける

12/2 ヤフーとLINEが経営統合して、あらゆる決済ができるスーパーアプリを提供へ

11/18 Linuxによくある謎の記号による処理を説明変数で読みやすくする方法

11/4 アップルが HKmap.live を香港デモを支援するアプリと判断し配信停止

10/21 エラーが発生したときに例外を投げずに返り値としてエラーを返したときの問題

10/7 暗号化PDFを開こうとパスワードを入力すると流出する脆弱性

9/23 Go 言語でよく defer される Close 関数のエラーを捕まえる

9/9 多くの Web サービスのインフラを提供している aws に障害発生

8/26 POSIX の ls コマンドで表示される一覧の区切りの空白は2文字

8/12 Google が Chrome のシークレットモードで有料記事を無料で読める機能を強化

7/29 プログラムとしての定数と仕様としての定数を明確に分けること

7/15 電子決済サービス開始で再び不正利用。7pay の対応の問題とは

7/1 インストール手順にバグがある原因は、スクリプトを作っていないから

6/17 音楽権利情報処理にAWSのブロックチェーン技術が採用される

6/3 インストーラーでインストールする対象のバージョンは、最新版より特定版

5/20 PC上での共同作業をインテリジェンスにする Fluid Framework

5/6 Windows で Python スクリプトを Python の仮想環境の中で起動する方法

4/22 Windows で USB デバイスの安全な取り外しの操作が不要に

4/7 ブール型の説明変数の名前は文にする - リーダブル コード(60)

3/25 グーグルがゲーム ストリーミング サービスに参入、STADIA を発表

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

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

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

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

もっと前の記事

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

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,