パスワードを忘れた? アカウント作成
166095 story
プログラミング

コメントはソースコードを表す? 161

ストーリー by hylom
まずはコメントの書き方を教えるべき? 部門より

あるAnonymous Coward 曰く、

本家「If the Comments Are Ugly, the Code Is Ugly」より。

Esther Schindler氏は自身のブログでソースコードとコメントの関係について次のように書いている。「オープンソース好きでプログラミングに携わっている者だろうが、生活のためにコードを書いている者だろうが、プログラミングが細やかな注意力が必要な作業であることには変わりない。ソフトウエアを書いている者は重箱の隅をつつくような細かさがなければ動くコードは書けない。コメントに言い訳まがいのくどい説明などが書いてあれば、その開発者は恐らく自分の書いているコードをきちんと把握していなかったに違いない。」

コメントはそのソースコードを表すだろうか?例えばコメントに文法上の間違いが見受けられる場合、コードにも重大なエラーが潜んでいるものだろうか?

/.Jerの経験ではいかがだろうか?

この議論は賞味期限が切れたので、アーカイブ化されています。 新たにコメントを付けることはできません。
  • by baku3393 (32616) on 2009年11月19日 12時15分 (#1674993) 日記
    「Ugly」の解釈がプログラマーと非プログラマーで異なると思います。

    文法が正確で誤字の少ない簡潔なコメントが書けても、そもそもクラス名とかメソッド名とか変数名
    が非直観的だったり、インデントが深すぎだったりしたら「コード」としては「Ugly」です。

    あと、修正前のコードをコメントアウトして残すことを強制されたコードも「Ugly」。
    バグ票番号を修正箇所にゴチャゴチャ残させるコードも「Ugly」。

    逆に、何にもコメントがなくてもコード自体が短くて直観的でコメント自体が不要なものであれば
    「美しい」コードだったりします。

    むしろプアでしゃくし定規な「コーディング規約」なる法典をおしつけられて無理やりコメントを
    書かされていると冗長な説明文が入った「見た目にキタナイ」ソースになっちゃったりします。

    コメントもコードも「言語」ですからね。

    #ってか、「非プログラマ」な人種はソースなんて見るのか?(<俺)
    --
    ---- ばくさん!@一応IT土方
    • by Anonymous Coward on 2009年11月19日 13時56分 (#1675080)

      > 逆に、何にもコメントがなくてもコード自体が短くて直観的でコメント自体が不要なものであれば
      > 「美しい」コードだったりします。

      内容は賛成ですが、万人にはお勧めできないと思います。
      「自称」やり手プログラマの中には、
      コメントがなければ美しいコードだと勘違いしている人がいるようなので。

      以前、ソースコードにコメントがなくて理解できないことを書いた本人に言うと、
      「コメントがなくてもわかりやすく書いてある」
      と言っていたのですが、そのソースコードの不具合改修をお願いすると
      「書いてから時間が経っていてプログラムを解析する必要があるので、修正するには時間がかかる」
      と言ってました。
      そのためのコメントじゃないの?

      同様に「プログラマならemacsだろ!IDEなんか必要ない!」みたいな考え方の人もどうかと思います。

      親コメント
      • > そのためのコメントじゃないの?

        コメントが書かれているからといってプログラムを
        解析する手間がなくなるわけじゃない。

        だってコメントが書いてあってもそれが正しいという
        保証はない。

        だから必ずコメントとコードが整合しているかチェックしなくちゃ
        いけないけど、これがコードを直接、解析するより楽かどうかは
        コメント(とコード)の品質による。

        「優れたコメントは優れたコードと同じくらいプログラムにとって重要だ」

        という言葉を聞いたことがある。(ストールマンがいってたような…)

        しかし私は言おう。

        「劣悪なコメントは凶悪なバグと同じくらいプログラムにとって有害だ」

        親コメント
      • >「自称」やり手プログラマの中には、
        >コメントがなければ美しいコードだと勘違いしている人がいるようなので。
        こっちの指摘はまあまあ理解できるけど、

        >そのためのコメントじゃないの?
        それは必ずしも正しくないと思う。
        コメントがあった方が良い局面というのはあるけれど、コメントがあればデバッグのための
        ソースの解析が不要になるかというとそんなことはない。

        たとえ自分が書いたプログラムやコメントでも、書いてから何年もたてば自分が書いた
        内容の細部なんて忘れてしまいます。まして自分が当時気付かなかったミスについて
        修整を頼まれたんだから、自分が当時正しいと思っていた仮定なんてあてになりません。

        例えば,自分で書いた推理小説の密室トリックのアラを読者に指摘されて、推理小説の
        辻褄があうようにトリックを書き直そうと思えば小説全体を読み直して書き換える必要が
        ある。それには相応の時間がかかるのは避けられないと思います。

        >同様に「プログラマならemacsだろ!IDEなんか必要ない!」みたいな考え方の人もどうかと思います。

        「IDEが使えない人」は困ると思うけど、IDEを使う必要は実はそんなにないと思います。
        しょせんIDEなんて、単体のツールを集めただけの代物なんだから。

        むしろ「IDEさえ使えればいい」、「単体のエディタなんて時代遅れだ」と思ってる人
        の方がどうかと思います。そういう人はIDE付属の簡易エディタしか使ったことがなくて、
        本物のエディタを理解していないんですね。酷い場合だと除き窓のような細いエディタ
        領域の中から、横長で改行も入ってないようなコードを書いて平然としている人までいます。
        機能単位で関数を分けると分散して読みにくくなると文句を言う人もいます。

        あとJavaのように強力な型付けの言語で、それをIDEが解析して利用している場合なら
        まだしも、Rubyのように動的な片付けの言語や、PHPのようにぐ支離滅裂な言語だと、
        IDEの単体エディタに対する利点はかなり減るでしょうね。

        親コメント
  • クオリティは一致する (スコア:4, すばらしい洞察)

    by Anonymous Coward on 2009年11月19日 12時16分 (#1674995)

    コメントと実装がずれていた場合、設計書の内容も最新仕様と一致していない。
    という事で、プロジェクトの管理自体がうまく回っていない。・・・ケースが多い。

    個人的な経験では100%。

  • by Anonymous Coward on 2009年11月19日 12時20分 (#1674998)
    コードの表現できる範囲と、コメントの表現できる範囲は異なる。
    なので、それらを総合的に合わせて一番適切な表現になる様にするのがベスト。

    なぜそのコードが選ばれたのか?の意図はコードには表れない。
    コードは自分が何かは表わすけど、それだけ。選択の意図するものが
    最善なのか次善なのか、それともやっつけなのかわざとなのかはコードの記述範疇外だから。
    • by Anonymous Coward on 2009年11月19日 12時23分 (#1675002)
      そうですよね。なぜこのロジックを選択するに至ったか、もっとシンプルと
      思われる手法ではなにが問題だったかは長くなっても書いておくべきだと思います。
      ドキュメントは仕様を理解したらそんなに見ないですし。
      コメントが必要ないのが綺麗なコードなんていうのは80年代で終わってますから。
      親コメント
    • > コードの表現できる範囲と、コメントの表現できる範囲は異なる。

      俺はコメントには「機能」を書きますね。どういう目的か。処理内容じゃなくって。

      たとえば、0-9,a-z文字列("0123ab")をhex化(0x0123ab)するといった処理を書く場合、コードの塊の頭に
      「// 16進文字列をHEXに変換する(端数が出たら残りは0x0埋め)」
      とか。具体的に「// 文字列の長さを計測してループする」とか「// シフトして値をずらす」・・・とかって言うのはあんま書かないです。昔は書いてましたけど。

      ところで、自分のソースの中に含まれるコメントの割合って行単位だと皆さんどのくらいあるんでしょうか?いわゆるコメント量のお話。昔自分の書いたコードを計測してきた結果、俺は「約30%」がコメント行でした。個人的にはこれくらいあれば(程度の差をあまり気にせず)分かってもらえると思います。
      親コメント
  • by Anonymous Coward on 2009年11月19日 12時39分 (#1675014)
    >言い訳まがいのくどい説明など

    精度の低いコードを書く奴って、レビューで指摘してもウダウダ言い訳することが多いのは実感としてある。
    仕様を理解した上での解釈の間違いであれば、指摘すればすぐに納得してもらえるし修正も早い。
    また、「意味がわかんねーよ」とキレるのは、少なくとも「わかってない」という現実と対峙しているのでいいほう。
    たちが悪いのは根本的に理解が不足しているのにそれを自覚していない奴。
    概要レベルの仕様の解釈で屁理屈をコネ回す奴は、プロジェクトから外すのが正解。
    コードレビューの次元でそもそも論とか持ち出す奴は敬遠したほうがいい。

    ついでに過去の経験から言うと、変数名などの命名規約を独自解釈する奴は危険。
  • 経験あり (スコア:2, 参考になる)

    by Anonymous Coward on 2009年11月19日 12時14分 (#1674990)

    自信がないことを示すキーワードがある箇所は全部バグでした。
    (なぜか,とりあえず,苦肉の策,うまく)

    また、仕様書の曖昧なテキストがそのままコードコメントに貼り付けてあって、これもバグでした。
    (日本語の論理演算「または・かつ」と否定演算「ではない」の組み合わせ。人によって解釈がまちまち)

    ただ、コメントからのあら捜しは、かならずしもコードバグとは結びつかないので、絶対的なものではないですね。
    納品前に妙なコメントは除去されることもあり、そうなるとその痕跡は消えますし。

  • 自分の書いたソース? (スコア:2, おもしろおかしい)

    by Anonymous Coward on 2009年11月19日 13時24分 (#1675050)

    ノーコメントです。

  • by wish (6421) on 2009年11月19日 15時55分 (#1675207) 日記
    *個のコメントが現在のしきい値以下です。
    と、モデレート機能をソースレビュー時に付ければ良いのでは?
    あ、、、ソースも見れないや!コンパイルも げふんげふん。。。
  • by Tellur52 (36331) on 2009年11月20日 0時49分 (#1675645) 日記

    これは、私が昔体験した話です。

    メールを読むのにUNIXマシンにログインするのが当たり前だった頃、主に使っていたメーラーがMHでした。

    あるとき、MHの仕組みが気になって、ソースを追いかけ始めたのです。まあ、その頃もメールの流量に辟易していたから、incあたりから読み進めたんだろうと思います。

    程なく、MHの核心部分のライブラリに近づいたのですが、あるファイルを開いてびっくりしました。
    そのファイルは妙にサイズが大きく、中はおぞましいVAXのアセンブリ言語が散りばめられているのです。Cの部分も他のファイルとは雰囲気が全く違います。

    「これは古代の遺跡に当たってしまったかもしれない」

    と思いつつ、ふとコードの先頭のほうにある長いコメントを見ると、中ほどに恐ろしい文句が書いてあったのです。

    > If you hack on this and slow it down, I, my children and my
    > children's children will curse you.
    意訳:「コードいじり損ねたら、末代まで祟ってやる」

    「えー、なにふざけた事書いているんだこの野郎」と思いつつコードのメンテナの名前を見ると、

    Van Jacobson

    とあります。

    え、何、このchildrenって人間じゃなくてパケット、と思った瞬間、戦慄が走りました。まるで、インターネットの深遠にある暗がりに潜む宇宙的恐怖を見たような。

    それ以後、私は「MHのコードだけは決して触らない」と固く誓ったのでした。

    今でもRand社由来のMH(たぶん6.8.4など)はどこかのLinux系ディストリビューションなどでパッケージとして転がっていて、Van Jacobsonの呪詛もソースパッケージの中でそのまま保存されているようです。
    コードを紐解いていけばすぐに出会えるでしょうが、古いUNIXのコードですから、横着して

    grep curse *

    とやってはいけません。恐らく数多の呪いが貴方を襲うことでしょう。

  • コメントの例 (スコア:1, おもしろおかしい)

    by Anonymous Coward on 2009年11月19日 12時19分 (#1674997)
    char buff[MAX_SIZE + 100] // とりあえずちょっと多めに
    InitNNN(0, 0, 1, 0); // よく分からんけど参考例をコピペ
    h = WinInitialize(opt); // おまじない

    とかやったことあります。
  • コメントねえ (スコア:1, 参考になる)

    by Anonymous Coward on 2009年11月19日 13時19分 (#1675045)

    コメントをどうこう言う暇があったらそんなもん全部消して実際のコードに注力しろよ。

    あ、そういえばこんな話題が。
    http://blogs.itmedia.co.jp/morisaki/2009/11/post-8f5d.html [itmedia.co.jp]

  • by s02222 (20350) on 2009年11月19日 13時58分 (#1675082)
    > コメントに言い訳まがいのくどい説明

    出来る限りの最適化を加えてた結果としてどうしょうもなく読みにくくなって、それを緩和すべくくどい説明を添えることぐらいは許してください。

    単純なところでは、

    strcpy(dst + a + b + c, src); // 意図はstrcat(dst, src); ここまでの処理でstrlen(dst) == a + b + cなので

    みたいな、(この例だと変数名が最悪なのは置いといて)分かってる値を使い回してステップ数を減らすところから、もっと凝りに凝った最適化まで。

    ぱっと見て何が書いてあるのか分からない、と言う問題までは共通ですが、そういう場合に「じゃあどういう風に見て回ればその最適化で正しいと確かめられるか」のメモを残すよう心がけています。

    最適化しなくてもいいような場所は、そんなことよりロジック・ソースを分かりやすくて無駄に長いコメントを付けなくていいようにすべきですが。
    # argvの解釈を1ステップでも速くしようと血道を上げる最適化厨だった青春時代
    • Re:良い言い訳 (スコア:2, 参考になる)

      by okky (2487) on 2009年11月19日 15時20分 (#1675177) ホームページ 日記

      うしろから羽交い絞めにして、
      「やめろ、やめるんだ!!」
      「はなせっ離してくれっっ、ここを最適化しないと…ここを最適化しないとっっ」
      「ばかっ、そこで苦労してどうする。今じゃもう、gcc とかの最適化がそんな事は全部やってくれるんだっっ」
      「な…なんだって… じゃぁ、俺の今までの苦労は…」

      うん。もう同情に涙が止まりませんよ。gccの最適化の強靭さを見た瞬間の感動を君にも分けてあげたい。

      .

      ただ、そのためにコードを読みにくくするのは昔のコードであってもお勧めできません。

      「アセンブラで組め」
      「インライン アセンブリコードで組め」

      で、コメントにCの読みやすいコードを書くんだ。
      「いつか、良いコンパイラが出てきたら、このアセンブリコードは破棄するように」
      というコメントをつけて。

      --
      fjの教祖様
      親コメント
      • Re:良い言い訳 (スコア:3, おもしろおかしい)

        by Anonymous Coward on 2009年11月19日 16時37分 (#1675249)
        「そんなことはコンパイラがやる」
        「コンパイラなんかアテにならない」

        こういう小競り合いはしばしば見かけるが
        毎回共通していることがある

        どちらもコンパイラの出力を見ていない
        親コメント
      • by taka2 (14791) on 2009年11月19日 17時22分 (#1675293) ホームページ 日記

        コンパイラは「共通部分式の削除」だといった「小手先の最適化」はできますけど、
        アルゴリズムレベルでの最適化は無理ですね。計算量のオーダーは変わらない。
        計算量そのものが変わってくるような、例えば

        int sum(int n) {
            int i, accum = 0;
            for (i = 1; i <= n; i++) accum += i;
            return accum;
        }

        int sum(int n) { return (n+1)*n/2; }

        に書き換えるような最適化はコンパイラには無理で、そういうの手で書くしかないし、それを突き進めていくと、どうしても可読性は悪くなるんですよね。

        昔の自分が書いたコードで、「何を計算したいのか」「どういう式で算出しているのか」は一目瞭然なんだけど、
        「なぜその式で答えが出るのか」がさっぱり分からないという羽目になったことがあります。
        仕方ないので、ムダにもう一度悩んで悩んで、なんとかその通りに式変形できることを確認しました。

        それ以来、私はそういう処理をした時は、コメントに式変形過程を残したりしてますけど、そもそもテキストベースで「数式を書く」こと自体が難しいという問題があるんですよね。
        TeXスタイルは厳密な数式表現はできるけど可読性悪いし。
        結局、アスキーアート駆使して書いてます。

        親コメント
        • Re:良い言い訳 (スコア:2, 参考になる)

          by okky (2487) on 2009年11月20日 10時59分 (#1675799) ホームページ 日記

          アルゴリズムレベルでの最適化は無理ですね。

          そんな事はありません。Tail-Recursionコードをジャンプに変更する等は今でもやってくれて、スタック消費量などを大幅に削減してくれます。単に「あまりにも優先度の低いレアパターン」だから標準で組み込まれていないだけです。

          ようするに「無理」なんじゃなくて「無駄」なんですよ。

          一方で、sprintf( dst, "%s", src ) とかは gcc-4 でコードを吐けばわかりますが、
          strcpy( dst, src )
          に勝手に書き換えてくれます。

          --
          fjの教祖様
          親コメント
    • Re:良い言い訳 (スコア:1, すばらしい洞察)

      by Anonymous Coward on 2009年11月19日 14時57分 (#1675155)

      >strcpy(dst + a + b + c, src); // 意図はstrcat(dst, src); ここまでの処理でstrlen(dst) == a + b + cなので
      この程度の最適化はコンパイラに任せるべきだと思うし、コメントよりも
      const int offset_ここまでの処理でずれたと言うことがわかる名前 = a + b + c;
      strcpy(dst + offset_ここまでの処理でずれたと言うことがわかる名前, src);

      とかするとソースコードが意図を見せてくれると思うのだけどそういうのじゃだめなの?

      親コメント
      • by s02222 (20350) on 2009年11月19日 16時10分 (#1675218)
        >const int offset_ここまでの処理でずれたと言うことがわかる名前 = a + b + c;

        なるほど。・・・ただその場合、「この変数はソースを見やすくするためだけのものです」とのコメントがないと混乱しそうな気がするんですが、そういう気がするのがもはや時代遅れなのかなorz
        親コメント
        • Re:良い言い訳 (スコア:1, 参考になる)

          by taka2 (14791) on 2009年11月19日 17時02分 (#1675273) ホームページ 日記

          オフセットな変数を一時しのぎに作るから混乱するんでしょう。最初から

          strcpy(dst+dst_offset, src_a); dst_offset += length_a;
          strcpy(dst+dst_offset, src_b); dst_offset += length_b;
          strcpy(dst+dst_offset, src_c); dst_offset += length_c;

          って感じでやってれば問題ないかと。printf系は格納した文字数を返すので、この方法だと、

          dst_offset+=sprintf(dst+dst_offset, "%d", value);

          って出来て便利。最も、バッファオーバーフロー対策でsnprintfを使ったりすると、snprintfは「書き込んだ文字数」ではなく「必要な長さ」を返すので、この技が使えず、

          snprintf(dst+dst_offset, dst_rest, "%d", value); len = strlen(dst+dst_offset); dst_offset += len; dst_rest -= len;

          見たいな、効率面でダメダメなコードを書いたりすることもあったり。

          親コメント
typodupeerror

物事のやり方は一つではない -- Perlな人

読み込み中...