ジョブサポートのエンジニア研修ではソースコードの書き方はもちろん、コメントの書き方につい

ても研修中からしっかり指導していきます。新人SE・PGの教育担当はもちろん、自学でプログラ

ムの質を高めたい方にも活用できるのではないかと思います。弊社のJava研修の情報を活用して

ソースコードのどこに、どのようなコメントを書くべきかを説明していきます。

前回の「ソースコード(Java)のコメントの書き方①」では下記を記載しました。

1. ソース看板
2. javadoc
3. 特殊な変数

今回も引き続きソースコードのコメントの書き方の続きを記載してきます。

問題解決力を身に付ける若手、新人SE・PG向けの通年Java研修(1~3ヶ月コース)はこちら

■関連記事

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

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

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

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

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

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

若手、新人エンジニアの成長を阻む 人材育成5つの失敗と解決策はこちら

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

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

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

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

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

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

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

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

学歴、学部による「IT知識」「基礎知識」の格差を無くす個別指導の新人研修プロエンジニア育成

コース(Java2・3ヶ月コース)はこちら

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

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

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

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

　　　　　　　　　　　　特別な加工をしている。

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

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

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

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

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

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

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

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

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

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

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

レベルの向上にもつながりますので、面倒くさがらず、しっかり記述するようにしましょう。

■関連記事

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

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

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

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

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

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

貴社の希望日に合わせて受講できる個別指導型の短期Java講座(入門5日・基礎10日)はこちら

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

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

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

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

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

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

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

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

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

記述しましょう。

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

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

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

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

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

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

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

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

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

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

全国の若手~ベテランエンジニアが受講している個別指導のオンライン・リモート講座(入門5日・

基礎10日)はこちら

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

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

全国の若手~ベテランエンジニアが受講している個別指導のオンライン・リモート講座(入門5日・

基礎10日)資料ダウンロードはこちら