catch-img

ソースコードのコメントの書き方②


ブロックの先頭に概要説明を記述する


if や for/while、switch 等のブロックの先頭には、 そのブロックで行おうとしている

処理の概要を説明するコメントを記述しましょう。ブロックの先頭に説明を記述することにより、

そのブロック内のソースコードを読まなくてもそこで行おうとしている処理の概要が把握でき、

ソースコードをかいつまんで読む際にとても役に立ちます。

処理内容を要約するという役割において、コメントの効果は絶大です。



特殊な処理、際どい処理には、理由や意図を書く


プログラムは読みやすさを考慮して、できるだけ明快かつ自然な流れで、 安全で安定した処理に

なるよう記述するべきですが、 ときにはどうしても複雑で際どい処理を書かなければならない

場面があります。そのときは、後々他人または未来の自分がそのプログラムを読んだ時に、

「なぜこんな複雑な処理を行っているのだろうか?」と困惑してしまわないよう、

きちんと説明を記述しておく必要があります。

具体的には、記述したプログラムを読み返したときに、以下のようなイレギュラーな処理内容が

見つかった場合、 その理由や意図をコメントとして記述しましょう。


・変則的な処理  (例) 通常行わなくてもいいような処理を、わざわざ行っている。

・不順な処理   (例) 通常の処理手順からするとそこで行うべきではない処理を、

          あえてそこで行っている。

・特殊な処理   (例) データの単純な参照を行わず、文字列の部分切り出し等の

            特別な加工をしている。

・複雑な制御   (例) 処理を行うかどうかの制御や条件が複雑、または多い。

・複雑な処理   (例) 複雑なアルゴリズムを採用している。


もし、コメントを記述しようとして説明内容を考えたときに明確でもっともらしい理由や意図が

思いつかないようであれば、 そのプログラムのロジックに問題があるのかもしれません。

一度プログラムの処理内容を見直し、適切なロジックになるようコーディングし直してください。

コメントを記述する作業は、自分の頭の中を整理し直す作業でもあります。

この処理は何か? 何のための処理か? なぜこの位置で行っているのか? コメントは要るか?

というようなことを考えることにより、 時にはそのプログラムの不必要に複雑になっている

部分や無駄な記述に気付いたりすることがあり、それを修正することで、より読みやすくて

無駄のないプログラムに近づくことができます。

このように、コメントを書くことはプログラムの保守性を向上させ、

更に自身のコーディングレベルの向上にもつながりますので、面倒くさがらず、

しっかり記述するようにしましょう。


処理のひとまとまりに、目印になる要約コメントを書く


プログラムは読みやすさを考慮して、メソッドの処理が長くなりすぎないようにメソッドを

分割したりする必要がありますが、ときにはどうしても長い処理を書かなければならない場面が

あります。そのときは、長い処理の中でも関連する処理ごとに空行で記述エリアを分け、

そのひとまとまりに目印になる要約コメントを記述しておくと、長い処理でもだいぶ流れが

追いやすくなります。以下に、要約コメントの記述例を示します。



目立つコメントは、書きすぎに注意


上述のように目印になるような目立つコメントは、 要所要所に記述すると長いプログラムの処理が

追いやすくなってとても役に立ちますが、 記述する際は書きすぎないように注意してください。

本当はそれほど長くない処理だったり目立たせる必要がなかったりする場面で、 何でも目立つ

コメントを書いてしまうと、 処理の記述が埋もれてしまい逆に読みづらくなってしまうことが

あります。コメントに頼りすぎず、「うまくメソッド分割ができないか?」等、簡潔に記述する

方法もきちんと検討しましょう。


無駄なことを書かず、プログラムの理解のためのコメントを書く


コメントには、当たり前すぎることは書かず、プログラムを読む人の理解を

助けるための説明を記述しましょう。

日本語での説明のほうが分かりやすいからと言って、全ての処理一行一行に対してコメントを

書く必要はありません。 何でもかんでもコメントを記述すると、処理の部分が埋もれてしまい、

逆に読みづらくなります。 また、本当に注目すべき説明文が目立たなくなってしまい、

せっかく書いた注釈としてのコメントの効果が薄くなってしまうこともあります。


コメントを記述する際は、そのソースコードを他人が読んだ時にすんなり理解できるか?

そのままでは誤解や混乱を招いてしまうようなロジックになっていないか?

というようなことを考え、 コメントの要/不要を判断するようにしましょう。

当たり前すぎて説明する必要のない処理にまでコメントを書く必要はありません。

「これは説明しておかないとコードを見てもすぐには理解できないだろう」

と思われる箇所にコメントを書きましょう。


ジョブサポートの技術研修では経験問わず人(プログラマ)にも理解できる、読みやすい

プログラム、コメントを書くために早い段階から見やすいコードを書く習慣を身に付けます。

通年で随時研修の受け入れを行っていますのでお気軽にお問い合わせ下さい。






お問い合わせ

ジョブサポートのエンジニア研修(Java,JavaScript)の
お問い合わせはお気軽にご相談ください!
〒102-0072 東京都千代田区飯田橋 3-11-13 FORECAST 飯田橋 8階