最近、仕事で人のソースコードを読んでいるのですが、コメントが読みづらいと感じています。
私も初めてソースコードを書いたときは、ひどいものでした。
ですが、いまはだいぶ読みやすくなってきたと我ながら感じています。
そこで、初心者の方向けに、私がコードを書く際に注意している3つのことを、本記事で簡単に紹介したいと思います。
これを意識するだけでも、コメントがずいぶんと読みやすくなるはずです。
1.コメント「しない」ことを知る
コメントはたくさん書けばいいというものではありません。
たとえば、分厚い本、大量の文字、読みたくないですよね。
コメントも同じで、「コメントを書け」と言われたからといって、やみくもにたくさん書いても意味はありません。
それでは、書かない方がよいコードとは、どんなコードでしょうか?
それは、「コードを見ればすぐわかること」です。
悪い例
// aとbを足す int sum = a + b;
言われなくてもコードを見ればわかりますね。
改善例
int sum = a + b;
「コードを見ればすぐわかる」ことは、コメントしないようにしましょう。
2.読み手の立場で見なおす
2つ目は「読み手の立場を考えて、コメントする」ことです。
これはコメントに限らず、他人に見られるもの全てに言えることでもあります。
人に見られるものを作った際は、必ず「よく知らない人が見たらどう考えるだろうか?」ということを、自問自答することが大切です。
悪い例:省略されすぎた変数名
int a = w * h;
aってなに?
って思いますよね。
改善例:面積 = 幅 × 高さ
int area = width * height;
書いた本人しかわからないことを書いていないか、見返すくせを付けることが大切です。
3.ブロックごとにコメントをつける
最後は、「処理のブロックごとにコメントをつける」ことです。
たとえば、for文を使うときは必ず、行っている処理内容をfor文の前に書く、などです。
例
# 自分のレビューを表示する for review in all_reviews: if review.user_id == my_id: print(review.text)
ブロックごとでコメントを付けることで、複雑なコードを読まずに、処理の概要がわかるようになります。
積極的に処理ブロック単位で、コメントをしていきましょう。
まとめ
1.コメント「しない」ことを知る
2.読み手の立場で見なおす
3.ブロックごとにコメントをつける
以上、簡単にでしたが、コメントを書く際に注意していることでした。
楽しく読めるソースコードを世の中に増やしていきたいですね。
関連記事

コメント