読みやすい！ソースコードコメントの書き方３選

最近、仕事で人のソースコードを読んでいるのですが、コメントが読みづらいと感じています。

私も初めてソースコードを書いたときは、ひどいものでした。
ですが、いまはだいぶ読みやすくなってきたと我ながら感じています。

そこで、初心者の方向けに、私がコードを書く際に注意している3つのことを、本記事で簡単に紹介したいと思います。

これを意識するだけでも、コメントがずいぶんと読みやすくなるはずです。

１．コメント「しない」ことを知る

コメントはたくさん書けばいいというものではありません。
たとえば、分厚い本、大量の文字、読みたくないですよね。

コメントも同じで、「コメントを書け」と言われたからといって、やみくもにたくさん書いても意味はありません。

それでは、書かない方がよいコードとは、どんなコードでしょうか？

それは、「コードを見ればすぐわかること」です。

悪い例

// aとbを足す
int sum = a + b;

言われなくてもコードを見ればわかりますね。

改善例

int sum = a + b;

「コードを見ればすぐわかる」ことは、コメントしないようにしましょう。

２つ目は「読み手の立場を考えて、コメントする」ことです。
これはコメントに限らず、他人に見られるもの全てに言えることでもあります。

人に見られるものを作った際は、必ず「よく知らない人が見たらどう考えるだろうか？」ということを、自問自答することが大切です。

悪い例：省略されすぎた変数名

int a = w * h;

aってなに？
って思いますよね。

改善例：面積 = 幅 × 高さ

int area = width * height;

書いた本人しかわからないことを書いていないか、見返すくせを付けることが大切です。

最後は、「処理のブロックごとにコメントをつける」ことです。

たとえば、for文を使うときは必ず、行っている処理内容をfor文の前に書く、などです。

例

# 自分のレビューを表示する
for review in all_reviews:
  if review.user_id == my_id:
    print(review.text)

ブロックごとでコメントを付けることで、複雑なコードを読まずに、処理の概要がわかるようになります。

積極的に処理ブロック単位で、コメントをしていきましょう。

１．コメント「しない」ことを知る
２．読み手の立場で見なおす
３．ブロックごとにコメントをつける

以上、簡単にでしたが、コメントを書く際に注意していることでした。

楽しく読めるソースコードを世の中に増やしていきたいですね。