読者です 読者をやめる 読者になる 読者になる

l_n_m’s diary

よわい電気系の日記(本当にただの日記)

コメントの重要性

共同開発の要

コメントはコメントでも、プログラムのコード中のコメントのこと。ブログのコメントなんざ思ったことを好きなように書けばいいわけで、特に何か言いたいこともありません。

共同開発する上で重要なのは、自分以外の開発メンバー(以下メンバー)への説明です。プロジェクトの全容把握は大変。コードの書き方も人によって違いますから、いちいち全部読んで構造を把握するのは無駄な苦労を伴います。

そこでコメントです。一言、これは何をする関数である。これは何のための変数である。特に関数は、そういうことが書いてあるだけで内部を読まずとも動作が大まかに分かるのですから、非常に読み易くなります。

当たり前のことを突然どうした

なんでこんなことをぼやいているのか。

友人と一緒にやっているプロジェクトで、友人のコードに一切コメントが無く、変数名や関数名からおおよその動作を推測して、曖昧なら中身を読んで、……というのを1000行足らず*数ファイルやることになってしまったからです。

しかも使っているクラスやその継承元が別のファイルにあることも多々あり。VS先生が無かったら探すのも大変だったでしょう。友人は綺麗に分類してくれているので、スパゲッティなことにはなっていないのがとてもありがたいですが。

当たり前っちゃ当たり前です。面倒くさがらないで書けばいいのです。後でデバッグしたりリライトしたりするときに、自分の助けにもなります。というわけで書きましょう。どんどん書きましょう。

人のふり見て我がふり直せ

では自分を振り返ってみると。

関数の頭にほぼ必ずコメント付けます。それもしてないくせにこんなこと書いてたら何様だよってなります。ですが、それが本当に分かりやすいコメントなのかと言えば、その点はまだまだ改善の余地があります。

例えば純粋仮想関数には何を記述すればいいのか。仮想関数は仮想関数でまとめてヘッダに並べて書かれているか。

使いやすくするためにお節介な関数を定義する以上に、読みやすいコードを書くほうが親切だなと思いました。

自分で書いたコードを理解しているのは当たり前。その次の段階として、理解していない人でもすぐ理解できるような書き方が出来る、を目指したいです。まずは変数や関数の定義する順番なんかから気にしていけたらいいな。

ところで、日本語大丈夫?

読みやすいコメントを書くということは、人に読みやすい文章を書くということです。このブログもそういう文章のひとつ。ちゃんとした日本語を書く練習には持ってこいです。

夢中で書いていると言葉の順番がぐちゃぐちゃになってしまったり、主張が曖昧になってしまったりします。高校のときの作文なんて酷いものでした。思い出すと恥ずかしくて叫びだします。

トーク力にも通じるところがありますね。こんなんだから面白い話が出来ないんだろうな……。

言葉を伝えるのって難しいですね。頑張ります。

ところで、html大丈夫?

だめです。