プログラムのコメントについて

職業としてのプログラミング:省コメントのススメ

プログラムに対するコメントの考え方がだいぶ近い方を見つけた。
正確に言うと漠然と思っていたことがちゃんと纏められて書かれている。

今のところソースを組んだらこんな感じで実際コメントを記述していると
思う。(たぶん・・・)

ここらへの話題は私が目標とするプログラマの一人
「か」さんあたりが思うところありそうですがどうでしょう?

せつないぶろぐ:プログラム設計書
悪態のプログラマ:コメント論(7/25追加)

11件のコメント

  1. 指名されたので登場です。
    まあ、共感できるところはあるね。
    意味のわからない変数名はつけないというのはある意味当たっているが、省コメント化云々ではなくてプロとして当然のことではないですかね?
    しかし現実的には変数名から完全に意味がわかるような名前をつけることは不可能でしょう。
    個人的には変数名で15文字くらいまでいったら長いと感じるからやはり省略して記述する。
    (某N社のH嬢は平気で30文字くらいの変数名をつけるのでメンテナンスする側は大変だった…)
    これはやたら長いとソースの可読性が悪くなるし、入力時間も長くなるから。
    (余談だが以前やったシステムでテーブル名やカラム名を日本語で作りやがった会社があって、タイピングにやたら苦労した…。プログラムを作るというよりもドキュメントを書いてるような感じだった)
    そうすると処理の内容によっては似たような変数名も出てきてしまい、変数名から内容を把握するのは困難になってくる。
    ま、そうなったときにだけコメントを書けばいいという話なのかな?
    しかしそうなると個人的なコメント方針に反してしまう。
    個人的なコメントに対する方針を書いておきましょう。
    ・意味のあるコメントを処理(ブロック・関数)単位に書く
    ・美しく
    ・メリハリ
    基本的にはこんなもんかね。
    意味のあるコメントは当たり前だけど、できればコメントから処理内容を把握したい。
    いくらわかりやすい変数名でも、数ステップの処理を一読しただけで把握できるほど頭はよくない。
    それならばその数ステップの内容をわかりやすく短くコメントした方がいい。
    で、例えば一部のわかりづらい処理にだけコメントを書いたとする。
    そうするとソース全体を見たときに、部分的にはコメントがあるのに、部分的にはコメントがない。
    そうすると美しくない。
    ま、これは感性の問題だが。
    あとはメリハリね。
    短い関数ならあまり関係ないけど、処理的もしくは言語的にどうしても長くなってしまう場合もある。
    そうした場合に色々な処理をダラ~っとコメントも無しに書かれると区切りがわからない。
    最近の開発環境ならVisualStudioでもgvimでも秀丸でも色付きで表示されるだろうから、コメントがあったほうが可読性があがる。
    なんかうまくまとまらないけど、とにかくソースを追うのには日本語のコメントがあったほうがいいということ。
    ・プログラム→脳内コンパイル→処理内容把握
    ・日本語コメント→処理内容把握
    この2つを比較した場合、どちらが効率がいいかは一目瞭然でしょう。
    しかし改めて思ったのは、コメントを語るにはコーディングの方法についても語らないといけないかな、と。
    if文が5回ネストするプログラムよりは、if文が5回連続するプログラムの方が(個人的には)わかりやすい。
    汚いプログラムにいくら意味のあるコメントを書いても全体的に見たら意味がない。
    なんか話が逸れてきたので話を戻す。
    で、更に思ったのはプログラムもドキュメント(本)と一緒ではないかと。
    ドキュメントを書くときには必ず見出しを書くでしょう。
    それがコメントに相当する。
    いきなり箇条書きがはじまっても、それが何について書かれているのかわからないから、見出しをつける。
    本のタイトル=1ソース(ファイル)のコメント
    章タイトル=関数単位のコメント
    節タイトル=処理単位のコメント
    じゃないですかね。
    日本語のドキュメントですら見出しがなくなったら何が書かれているかわからなくなるのに、プログラムだったら…。
    以前別の会社の人が言っていたが、コメントを拾っていけば全ての処理内容(処理の流れ)がわかるようなコメントを書け、と。同意。
    本で例えれば目次を見ればその本の概要がわかる。それと一緒かな。
    まとめると『プログラム=本』ということで。
    なんか長い上に全然まとまりがなくてすんません。

  2. tさん、TBありがとうございます。「か」さんもコメントありがとうございます。参考になります。
    > コメントを拾っていけば全ての処理内容(処理の流れ)がわかるようなコメントを書け、と。同意。
    確かにひとつの指針ですね。でも、私はその前に「コメント無くても処理内容がわかるようなコードを書け」ということを考えます。極論すれば、コメント無しで理解できるコードを書きたいところです。
    とはいえ、「か」さんのおっしゃるように、人間は所詮自然言語で考えるものなので、適切なコメントがあった方が可読性はあがります。コメントが少ないことが良いことではありません。
    コメントに対する私の考えを一言で表すとすると、
    「コメントとプログラム(実コード)を合わせて必要十分な構成でソースを書く」
    ということになるでしょうか。
    今後ともお願いします (^^)。

  3. か さん、progerさんコメントありがとうございます。
    私なりに考えたのですが、ソース内の情報を2者に伝える必要があることが原因なのだと思います。
    CPUに伝える記述と閲覧する人間に伝える記述。
    前者がプログラムで後者がコメント。
    そもそもプログラムは両者にわかるようにと低級言語から高級言語に移ってきた経緯がありますが、それは英語圏の人間に対してです。
    よって英語圏内ではソースを見てわかるプログラムはもしかしたら可能かもしれませんが英語圏外ではある程度のコメントは必要となるかもと思い始めています。
    もちろんこの前提はプログラムがぱっと見で(人間的に)処理の大枠が分かるレベルで記述されていることが必要となります。
    そういった意味で日本語プログラムなんてひとつの回答かもしれません。
    ※それでも意味の無い変数名をつけたりしたら結局読めないソースになるのですが・・・
    [link:nadesi.com/]日本語プログラム:なでしこ[/link]

  4. 空行できませんね。
    ブログのソースいじってもいいのですが、バージョンアップしたときの対応とかめんどくさいのでこのままにしますね。
    すんません

  5. 悪態のプログラマです。TB ありがとうございます。
    私の考えは、か さんに非常に近いと思います。『プログラム=本』というのは、私が「新聞や雑誌の見出し」と書いたのと同じことを言われているのだと感じました。
    書籍にせよ、雑誌にせよ、見出しが無くて、全て同じフォントで本文の文章だけがびっしり書かれていたらどうでしょうか。確かに、伝えたい情報は全て載っているのでしょうが。。。

  6. > よって英語圏内ではソースを見てわかるプログラムはもしかしたら可能かもしれませんが…
    個人的には英語圏であろうと日本語圏であろうと、コメントは必要と思っています。
    しかし10年くらい前に『ディセント』っていうPCのゲーム(海外製)のソースを何故か入手したのだけど、それを見るとコメントは皆無。
    ゲームだから莫大なステップ数なんだけどほとんどコメントは無かった。
    それを考えるとあながち有り得ない話でもないのかな、と思った。
    でもゲームの場合、頻繁に改修するわけでもないし、コメントなんか入力してる暇があればガンガン作らないといけないのかもしれない。
    オープンソース系のプログラムを見てみると参考になるかもね。
    それこそ幾多の人が見て手を加えるのだから、きっとわかりやすいプログラム、コメントになっている、はず?
    > そういった意味で日本語プログラムなんてひとつの回答かもしれません。
    『ぴゅう太』に代表される(?)日本語プログラムはあくまでもプログラムのひとつの形であってとても生産性は望めないと思う。
    (この前書いた日本語のDBのことがあるので)
    もっとも、すごい開発環境を装備してマウスでクリックしていくだけでできちゃうとかなら話は別だが。
    でもそこまでくると日本語は関係ないか。
    コメント論は楽しいな。

  7. >オープンソース系のプログラムを見てみると参考になるかもね。
    >それこそ幾多の人が見て手を加えるのだから、きっとわかりやすいプログラム、コメントになっている、はず?
    するどい!
    なんでJavaのソースを覗いて見たのですがときたまコメントありますね。
    内容は処理の説明レベルかな。
    なので英語圏であっても伝えきれない情報はやはり文章にする必要がありそうです。

    でもやっぱり英語圏外だからコメントを書くこともあると思います。
    だって日本語プログラムのソース内に日本語のコメントって違和感ありませんか(処理の説明レベル以外)。これってソースとコメントが重複することからくる違和感だと思います。

    Javaのソース見ててオブジェクト指向と構造化プログラミングでもコメントに違いがでそだなと思いました。
    オブジェクト指向だとソースの単位がメソッド(関数)よりクラスな気がします。なのでメソッドは非常にソースが短い。よってコメントをはさむ余地がほとんどありません。

    構造化プログラムだとソースの単位が関数になり、メインルーチンあたりからいろんな関数を呼び出す作りとなると思います。そうなるとメインルーチンにはコメントって必要だよなって気がします。呼ばれる側は関数のヘッダー部分にコメントがあればOKではないでしょうか。

    Java(オブジェクト指向)側も結局はクラスを呼び出して使う部分に関しては同じ気がしますが、単位をクラスと書いてしまったのでそこは無視して下さい。
    で、Javaのメソッドを追おうとすると全体間がよくわからなくなかなか使い難い。これを解消する為にJavaDocなんてものがあるのではないでしょうか。
    なんかそれちゃった気がしますが私のブログなんでありでしょう。

    >コメント論は楽しいな。
    このブログでは最多コメント数です。楽しんで頂いて嬉しく思います。

  8. 横からすみません。
    英語と日本語で比べると、漢字という表意文字を使える日本語のほうが、視認性というか速読性(?)が高くなるような気がします。そういう意味でも、英語より日本語の法がコメント向きなのかも。

  9. 『ぴゅう太』を誰もつっこんでくれないのが寂しいですが…

    > argvさま
    確かに日本語の方が視認性がいいですよね。
    プログラムと同じ言語で書かれていると、コメントなのかプログラムなのかがはっきりしない。
    いや、じっくりと見ればわかるけど、パッと見だとわかりづらい。
    そう考えるとプログラミングは2バイトコード圏向きですかね。
    でもまあ、最初にも書きましたけど、エディタ上で色分けされるので今の時代はあまり関係ないのかもしれません。

    「木を見て森を見ず」が僕の好きな言葉なんですが、これってそのままコメント論に適用できそうです。
    いくらわかりやすいコードを書いても、ステップ単位(木)には理解はしやすいが、全体(森)を見るとコメントがないとどんな内容なのかがわからない。
    「木を見て森も見る」じゃないと僕はダメみたいです。

  10. ぶっちゃけコメント論は宗教論に等しいので解答は人それぞれでしょうが
    なんかいい議論ができたな。って思いです。

    まあ英語圏やオブジェクト指向といった話題も振りましたが
    基本的にはprogerさんのコメント派です。

    ただし宗教のように「か」さんやargvさんの内容が間違っている
    なんてことはさらさら思わず、それも判る。なんて立場です。

    みんながこれぐらい考えてソースを組んでくれればいいものできると
    思うんですけどね。

コメントを残す

メールアドレスが公開されることはありません。