IT ニュース＆コラム    2020/ 1/20   通巻805号  技術版

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

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


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


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

    // docx ファイルを保存する
    docx.SaveAs( path_of_word_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 )

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

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

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

    （前のブロック）

    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を残せ！
  https://www.ishikawa-nandemo.com/code-comment-why/
・良い？悪い？コードコメントの書き方 
  https://www.slideshare.net/ssagawa/ss-14579535
・リーダブルコード - より良いコードを書くためのシンプルで実践的なテクニック
  8.1章 説明変数、8.2章 要約変数

第803号で予告したプロパティやメソッドにデータ定義を書く場合については、次回説明します。



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


◇ Googleの元国際関係責任者が退職、Googleは邪悪になってしまったと退職の理由やGoogleの内情を暴露。
https://gigazine.net/news/20200107-why-ex-google-policy-chief-left/
 … 社内チームがこっそり中国共産党に加担しているグーグル。

◇ Googleが天才的スパイアプリ疑惑のToTokをPlayストアに復活させる。
https://gigazine.net/news/20200107-google-back-play-store-totok/
 … グーグルという会社がおかしい。

◇ 自ら電気を生み出す バッテリーレス IoT にぴったりなマイコンチップ ONiO.zero が登場。
https://gigazine.net/news/20200112-onio-zero/
 … 携帯電話の電波をエネルギー源として発電してチップを動かす。

◇ まだ半数以上の企業がサポート終了したWindows 7を使い続けている。
https://gigazine.net/news/20200115-windows-7-not-dead-yet/
 … 公共部門でより多く使われているらしい。

◇ トヨタが構築予定の自動運転・ロボット・AIが組み込まれた実験都市 Woven City の全貌とは？
https://gigazine.net/news/20200107-toyota-future-woven-city/
 … 公道でできない自動車の実験ができる施設にAIの実験も。

◇ 画面キャプチャで数式をLaTeX形式に自動で変換してくれる Mathpix Snip を使ってみた。
https://gigazine.net/news/20200106-mathpix-snip/
 … まだLaTeXを使っている人は便利かも。

◇ GoogleはChromeでユーザーエージェント文字列を段階的に廃止する方針。
https://gigazine.net/news/20200115-chrome-phase-out-user-agent-strings/
 … ユーザーエージェントに変わる特定方法を見つけたのかもしれない。

◇ Microsoftの無料コマンドラインアプリ Windows Terminall がブラウン管ライクな見た目に変身可能に。
https://gigazine.net/news/20200111-microsoft-windows-terminal-retro-style-crt/
 … タブ付きターミナル。

◇ Googleがスマートスピーカーに関する特許を侵害したとオーディオ企業がGoogleを提訴。
https://gigazine.net/news/20200108-sonos-sue-google/
 … グーグルの最強弁護士は特許さえ無効化する論理を持っていそう。

◇ 人気YouTuberがApple Watchにより命の危機から救われる。
https://gigazine.net/news/20200115-apple-watch-save-youtuber/
 … 科学的に判定しているので信頼できそう。

◇ Chromium版 Microsoft Edge が正式公開、実際に使ってみるとこんな感じ。
https://gigazine.net/news/20200116-chromium-microsoft-edge/
 … YouTube の反応が遅い嫌がらせを受けていたが、早くなった。



2020年より、IT ニュース＆コラムは 3週に1度の配信となります。


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