2006/09/05

ソースコード内のコメントは何%がよいのか?


ソースコードのコメント率は20%を切ることが望ましい (小野和俊のブログ)

正直、ソースコードの「コメント率」というものを、今まで考えたことがありませんでした。他の人が、後からソースコードを読んだときに、わかりやすいコメントであればOKぐらいに考えていました。

あぁ、やっぱり、ヘタレSEだ。。。orz

まぁ、それはさておき。

この記事によると、ソースコードのコメント率は20%を切ることが望ましいとされています。一方、従来は、ソースコードのコメント率が50%を切るものは品質が悪いとされていました。

20%の理由としては、可読性やメンテナンス性があげられていますが、そもそも、コメントをつけなければ分からないようなコードを書くべきではないということのようです。数値自体は経験則っぽいですね。但し、公開されるAPIとトリッキーな実装については、コメントを付けるべきとされています。

確かに、コメントが多くなると、ソースコードとコメントの同期をとる作業に時間が取られてしまうので、コメントなしで内容を理解できるのは、いい状態ですね。

ただ、これには、コメントなしでも他のメンバーが理解できるようなソースを書くスキルがプログラマにあるということと、他のメンバーも、ソースコードを見るだけで内容を把握できるというスキルが必要になります。

技術力が高くない組織にとっては、ちょっとハードルが高いかも。。。


コメント!=ドキュメント(404 Blog Not Found)

こちらの記事では、コメントの付け方が昔と変わったのは、以下の理由とのこと。
  1. 言語仕様が変わり、変数名の長さなどの制限がなくなったり、便利な関数が増えた
  2. ソース内で、「コメント」と「ドキュメント」の分離が可能になった
2については、PerlのPODが始まりのようで、それがJavaDocなどに引き継がれたようですね。

この理由は納得です。

また、コメントを付けるべき場所については、あくまで自分が迷ったり勘違いした部分につけるべきで、他人が分かりにくそうな部分につけるのではないとのこと。

これは、Perl Best Practicesで以下のように述べられているそうです。
Comment that has puzzled you or tricked you.
あなたが迷ったり勘違いしたところをコメントせよ
ふーむ。コメントの付け方1つでも、いろいろあるんですね。

勉強になります。

ソースコードのカウントの方法については、小野和俊氏の記事内に、「コメント書うんた」が紹介されていました。なかなかよさそうなツールです。


(2006/09/05 19:37update)
文章の意味が逆になってる部分があり訂正しました。
asdfさんご指摘ありがとうございます!

feedpath tags: ,   generated by feedpath

スポンサーリンク


このエントリーをはてなブックマークに追加




Twitter ではブログにはない、いろんな情報を発信しています。


コメント

コメントを書く



プロフィール

  • 名前:fnya
    経歴:
    SE としての経験は15年以上。様々な言語と環境で業務系システム開発を行い、セキュリティ対策などもしていました。現在は趣味SE。

    Twitter では、ブログでは取り上げない情報も公開しています。


    ブログについて

    このブログは、IT、スマートフォン、タブレット、システム開発などに関するさまざまな話題を取り上げたり、雑感などをつづっています。

    >>ブログ詳細
    >>自作ツール
    >>運営サイト
    >>Windows 10 まとめ

    Twitter のフォローはこちらから Facebook ページはこちら Google+ページはこちら RSSフィードのご登録はこちらから