ソースのコメントって、ブロック単位につけるようにすると上達するよ

プログラムのソースのコメントの話です。

処理をみたら分かるんだから、コメントなんて必要ないとかいう論理をかざす人たちもいるんだけど、
英語文化圏の人のソースだって、コメントちゃんと書かれてるのをみれば、コメントが一切無用なんてことないことは明白だと思う。

そもそも、言語仕様レベルで、コメントかけるようになってるのはなぜ？という部分もあると思うが・・。

みんなさー、ソースにコメント書け書け言うけどさー、コード直してもコメントは直さないじゃん？
だったら書かないほうがマシじゃん？
みんなさー、ソースにコメント書け書け言うけどさー、コード直してもコメ..

コメントを書くのが苦手、下手な人の特徴として
プログラムソース１行ずつに、コメントをつけようとする傾向があると思う。

コメントを何のためにつけるのか？とかそういうのを考えないというか
自分さえ分かれば問題ないとか、自己防衛の為に情報を残しておこうとか
そういう思考がないのかなぁと個人的には思う。

まあ、ブロック単位でコメントを書くように意識づければ、そこそこマトモなコメントをつけれるようになる人がほとんどだと思うので、前向きに頑張りたい人はそうすればよいかと思う。

意地でもコメントを書きたくない、コメントなんで無駄なんだというのを貫きたいのなら、それらしい論理を集めて、啓もう活動を頑張ればよいかと思う。

コメントのつけ方のコツ

（1） コメントは要約や意図を記述する
（2） 行末コメントは付けない
（3） ソースコードを見直すことも考慮する
（4） ソースコードを修正するときはコメントも見直す
第１３９号（2011年6月1日発行） 技術レポート「効果的なソースコードのコメントについて」｜ソフテックだより｜株式会社ソフテック

ソースを修正するときは、コメントも見直すのは普通

ソース修正した時に、コメントが修正しにくいとかがあるんだとしたら、コメントのつけ方が不味かったんだと思います。まあ、それでもコメントも修正しないとダメですけどね。

要約や意図を記述するということは、処理のブロックに対してコメントをつけるというのとほぼ同じだと思ってよいと思います。

たとえば、そのコメントを読んで、処理の内容を良そうで来たら、ソースを読むときに解読が簡単になるとかそういう感じだと思えばよいかと思います。

コメントを行単位につける人は、コメントをつけるのが下手な傾向にある

コメントの単位

さきほどは、コメントの目的で分けましたが、こんどはコメントの単位でわけます。
コメントの単位で分けた場合、以下の単位でのコメントが考えられます。
行末コメント
パラグラフのコメント
データ宣言のコメント
制御構造のコメント
ルーチンのコメント
モジュールのコメント
上の方が範囲が小さく、下の方が範囲が大きいです。
よいコードであれは、それぞれの行でコメントをする必要は殆どありません。行にコメントが必要な理由は、「その行がすごく複雑で説明がいる」「かつてエラーがあり、それを記録しておきたい」の２つです。頻繁な行末コメントは、インデントや修正の際に邪魔になるだけですので、避けましょう。

コメント - いいプログラムを書こう

分かりやすいコメントをつけているのを見るのが一番だとおもうけど、
コメント苦手な人って、分かりやすいコメントをみても、それを分かりやすいと認識できない傾向にあるかと思う。

ということで、もっと機械的に、ルールを決めてコメントのつけ方を見直すのが上達するのに近道ではないか？と思う。

見やすければ、無駄なコメントがあっても良いとは思う

初心者向けの入門書ばりに初歩的な内容のコメントだったら、書くのやめてくれる？
//足し算
とか
//ループする
とか
見ればわかるから
初心者向けの入門書ばりに初歩的な内容のコメントだったら、書くのやめて..

最初は、どの程度、どのような内容を書くべきか分からないと思うので、上記のようなコメントをつけてもイイと思うんですね。

ただ、そのコメントをつけることで見にくくならなければ問題ないと個人的には思います。

読むほうだって、流し読みするわけで、必要ない情報（コメント）は読み捨てるとか普通にできるので気にならない人ほとんどだと思います。

････

・コメントの9割は無駄！～アンチプラクティスから学ぶ洗練されたコメントの書き方～ #code #コード｜CodeIQ MAGAZINE

コメントの9割は無駄！～アンチプラクティスから学ぶ洗練されたコメントの書き方～ #code #コード｜CodeIQ MAGAZINE

記事はその通りだと思うけど、悪いコメントは後で消せるので、最初はコメント多めに書いてもいいとも思う。

2013/12/17 01:07

僕もこのスタンスがよいとは思う。
失敗もしながら、試行錯誤という過程をえないで、最適なコメントをかけるようになる人なんて、ほとんどいないと思うから。

コメントの9割は無駄！～アンチプラクティスから学ぶ洗練されたコメントの書き方～ #code #コード｜CodeIQ MAGAZINE

• [開発]

大体リーダブルコードに書いてあったような気がする

2013/12/17 09:54

たぶん、そうでしょうね。