プログラム(ソースコード)へのコメントについて
プログラミングの入門書を読むと、「コメントを積極的に書きましょう」とあったり、「説明用のソースコードの言い換えているだけのコメントの例」があったりします。
プログラミングを勉強した手の時は、動作を理解しているか確かめるために1行筒コメントを付けるのもありかもしれません。
しかし、プログラミングになれてきたら、コメントの書き方にも注意を払いたいところです。
この文章自体が、コメントの書き方を考えよう派になっている気が....
コメント賛成派 vs.反対派
- 賛成派:どんどんコメントを付けましょう
- 反対派:コメントを付けなくてもわかるようなプログラムを書きましょう
コメントの分類
以下のレポートでは、コメントを5つに分類しています。
技術レポート「効果的なソースコードのコメントについて」 http://www.softech.co.jp/mm_110601_pc.htm
-(1) ソースコードの繰り返し
ソースコードの繰り返しは、ソースコードに書かれている内容を自然言語で言い換えただけの内容です。
-(2) ソースコードの要約
ソースコードの要約は、数行のソースコードを1つの文にまとめたものです。
-(3) ソースコードの意図の説明
ソースコードの意図の説明は、ソースコード内容の目的を説明したものです。
-(4) ソースコードの説明
ソースコードの説明は、複雑なソースコード、注意が必要なソースコードを説明した内容です。
サンプル
-
コメントの悪い例
-
ソースコードで発見した奇妙なコメント集 | Webクリエイターボックス http://www.webcreatorbox.com/webinfo/comments-source-code/
-
プログラミングメモ日記 危険なコメント http://qwertyfk.blog16.fc2.com/blog-entry-99.html
-
不適切な情報
-
退化コメント
-
冗長なコメント
-
記述不足なコメント
-
コメントアウトされたコード
-
ジョーク
-
公開されたMS-DOSとWordのコードには数々のジョークやイタズラが隠されていた - GIGAZINE http://gigazine.net/news/20140327-hidden-joke-in-code/
読みやすいプログラムに向けて
アルゴリズムとデータ構造
わかりやすいアルゴリズムでわかりやすいデータ構造を用いると、プログラムが読みやすくなります。
アルゴリズムの勉強のしかた - きしだのはてな http://d.hatena.ne.jp/nowokay/20110922#1316676007
ネーミング
新人プログラマーに読ませて欲しいネーミングの大切さ - プログラマー幸福論 http://kenji-namba.hatenablog.jp/entry/20120927.html
English - モデルやメソッドに名前を付けるときは英語の品詞に気をつけよう - Qiita http://qiita.com/jnchito/items/459d58ba652bf4763820
インデント
Apple史上最悪のセキュリティバグか、iOSとOS XのSSL接続に危険すぎる脆弱性が発覚──原因はタイプミス? | アプリオ http://appllio.com/20140223-4899-apple-ios-bug-ssl-goto-fail
コーディング規約
プログラミング(コーディング)時に決めておく約束事
-
命名規約
-
コーディングスタイル
-
禁止事項
-
些末なコードレビュー - naoyaのはてなダイアリー http://d.hatena.ne.jp/naoya/20140313/1394664578
コーディングスタイルは宗教戦争に発展する。
(他に宗教戦争に発展する話題として、エディタ宗教戦争、プログラミング言語宗教戦争などがある。)
- コードのインデント幅(2,3,4,8の派閥あり)
- {}の配置
- 命名規則
- 省略表記の扱い
- 繰り返し表記
- グローバル変数を使わない
- ……
コーディング規約を決めて、機械処理!
- lintツール
おもに、C言語のソースコードに対して、詳細かつ厳密なチェックを行うプログラム - エディタの自動フォーマット機能
Processingの場合は、Ctrl+T (Auto-Format)
Eclipseの場合は、CheckStyleプラグインとか
コードレビュー
小野和俊のブログ:コードレビューについて http://blog.livedoor.jp/lalha/archives/50495777.html
良いコードデビューと悪いコードレビュー