̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ IT ニュース&コラム 2013/ 8/ 5 通巻631号 技術版 ソフトウェアデザイン館 Sage Plaisir 21  ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ 要約コメントを自然言語だけにするな - リーダブル・コード(7) プログラムのソース・コードは、プログラムを論理的に表現するためのもの なので、論理を的確に表現できますが、人間が読むのには適さないことが よくあります。 そんなときは、コメントを付けますよね。 その一方で、自然言語(人間の言葉)を用いた設計書などのドキュメントでさえ、 誰でも読めるわけではないため、コードには必ずコメントを付けるというルールを 決めたところで、プログラムが読みやすくなるわけでもありません。 そうなると、コメントを読みやすくすること、というルールが作られるわけ ですが、主観的なルールは機能しません。 人によっては骨抜きにしますし、 人によってはレビュー時に余計な議論を生み、コストの増大になります。 書籍「リーダブルコード」の 5.3章の中にある「要約コメント」では、次の コード(Python言語)がサンプルで載っています。 # 顧客が自分で購入した商品を検索する for customer_id in all_customers:   for sale in all_sales[ customer_id ].sales:     if sale.recipient == customer_id: 上記のコメントは、すべて自然言語で書かれています。 人間が読むためのもの ですから自然言語にすべきなのは当たり前ですね。 と思うかもしれませんが、 自然言語がゆえに曖昧さが残ってしまっているので、実は適切ではありません。 顧客って具体的に何の変数のことであるかは、ソース・コードの中を探さ なければなりません。 customer_id でしょうか、all_customers でしょうか。 答は customer_id(ID) を持つ顧客です。 顧客そのものは、ソース・コードには 表れません。 しかも、顧客が何かが分かるのは、ソース・コードの全体を 読まなければなりません。 また、「検索する」と書かれていますが、検索した結果はどの変数に入るので しょうか。 検索した結果は、顧客が自分で購入した「商品」ですが、商品に 該当する単語はありません。 答は sale(売上)の対象となる商品です。 よく間違えるのは、costomer_id に関する何かですが、customer_id が検索 対象ではないことは、ソース・コードの全体を読まなければなりません。 つまり、コメントだけを読んだところで、コードを編集するために必要な具体的な 変数などの名前を知ることができないのです。 しかも、コメントにある単語が 具体的に何を指しているのか理解するために、ソース・コードを解析しなければ ならず、場合によっては、コメントがある方が理解が遅くなってしまうのです。 私が考えるより適切な要約コメントは、次の通りです。 # Set "sale" of "sale.recipient == customer_id" in "all_customers" and "all_sales" for customer_id in all_customers:   for sale in all_sales[ customer_id ].sales:     if sale.recipient == customer_id: コードに存在するシンボルを " " で囲み、対象となるコード全体における最終的な 出力変数 "sale" を明示します。 そして、必要であれば、出力変数の意味を、 なるべくシンボルを用いて表現します。 シンボルを使うことのメリットとして、検索が使えることです。 すべての変数は、必ず前の処理の出力ですが、その処理を見つけるときに検索が 使えるのです。 しかも、多くの場合、処理は関数ですから、関数の説明を読めば 理解できます。 上記のサンプルの場合、sale を検索すると、2行目の sale が 見つかるので、そこを読むことになります。 関数ではありませんが、for in の 言語仕様から理解できます。 大きな違いは、1行目を読む必要がないことです。 コメントが Set "sale" だけでも、sale を出力している処理を検索していくことで、 理解できます。 つまり、要約において最も重要なのは、最終的な出力変数を示す ことなのです。(関数を示すこともありますが、詳しくは下記のリンク先を参照) もう1つ重要なことは、変数名や関数名が読める適切な単語であることです。 もし略語が使われていたら、出力変数を検索したところで、理解が難しくなります。 上記のサンプルのコメントは、次のようになってしまいます。 # Set "s" of "s.reci == c_id" in "all_customer" and "all_sales" この対策は、略語をやめることです。 書籍「リーダブルコード」にも、次のように 書かれています。 「ひどいコードに優れたコメントを付けるよりも、優れたコード のほうがいい。」 ソース・コードの変更が難しいときは、略語の説明を添えます。 よって、略語を 使うと逆に、(コメント含めると)ソース・コードが長くなることもあります。 しかも、コメントは、コンパイラーが無視するので、仕様変更やスペルミスに 弱いのです。 間違った情報を与えてしまう可能性も高まります。 ですから、 なるべくコメントはシンプルにすべきです。 アセンブリ・コードでは、特にコメントが必要になりますが、ここでも自然言語だけ にするのは適切ではありません。 むしろ、レジスター名などを用いてコメントを C言語風に書いた方が理解が早いコメントになります。 ただし、多くの変数を初期化する場合など、出力変数が多数あるときは、出力変数 のシンボルを必ず書くルールに従うと、コメントはソース・コードのコピーのように なってしまい、コメントの意味がありません。 その場合は、コメントにシンボルは 必須ではありません。 参考: リーダブルコード - より良いコードを書くためのシンプルで実践的なテクニック オライリージャパン ISBN-13: 978-4873115658 5.3章 要約コメント ソースコードが早く読めるようになる、シンプル・コメント - livedoor Blog(ブログ) http://blog.livedoor.jp/sage_p/archives/51850426.html 注目ニュース 一覧 ◇ 2.5GHz帯の追加割当、UQに認可。 http://k-tai.impress.co.jp/docs/news/20130726_609274.html … ごちゃごちゃうるさいことぐらいで、そっぽを向くのは公務員がすべきじゃない。 ◇ UQ、110MbpsのWiMAX 2+を10月末よりサービス開始 〜2017年には1Gbpsを予定。 http://pc.watch.impress.co.jp/docs/news/20130729_609534.html … 2.5GHz帯の追加割当が認可されて、多くの会員が恩恵を受けそう。 ◇ 電力危機は続く。節電意識、猛暑にかなわず、太陽光発電は限界露呈、九州。 http://www.sankeibiz.jp/compliance/news/130728/cpd1307282131002-n1.htm … 夏こそ太陽光発電、とはうまくいかない。 ◇ NEC、スマホ事業、前向きな撤退。脱モノ売りを加速。 http://monoist.atmarkit.co.jp/mn/articles/1307/31/news118.html … ガラケーやタブレットはもう少し続ける。 ◇ 不採用の理由は、PCに詳しすぎるから……だと? http://www.itmedia.co.jp/pcuser/articles/1307/31/news026.html … 望まれる社員は、自社製品が悪くてもそれを売ること。 ◇ WebフォントサービスのTypekit、日本語に対応。 http://news.mynavi.jp/news/2013/08/01/112/index.html … ただし、個人レベルなら月約200円と有料。 ◇ Windowsフォームの業務アプリをタッチ対応にする MultiTouch for Windows Forms 1.0J。 http://www.publickey1.jp/blog/13/windowsmultitouch_for_windows_forms_10j.html … ピンチ・アウトで、触っているウィンドウの中だけ拡大。 ソフトウェアデザイン館 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