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

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

高めたい方にも活用できるのではないかと思います。

弊社のJava研修の情報を活用してソースコードのどこに、どのようなコメントを書くべきかを

2回に分けて記載します。

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

■関連記事

読みやすいプログラムを書くには、コメントを書くことが大切

コメントがなくても十分読みやすいプログラムを書くべきではありますが、

それでもソースコードの要約やその処理の意図などを明確に緑色の日本語の文字で説明して

おくべきです。 そうすることで、ロジックを解析する手間が省けたり、ソースコードを

読んでもすぐには理解できないような情報を読む人に伝えたりすることができます。

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

ソース看板コメントを記述

各モジュールのソースコードの先頭部分の、packageとimportの間には、

ファイル名や作成日等を記述するコメントを書きましょう。

作成日や変更日、変更内容を記録することにより、ソースコードを読まなくても修正箇所や

変更箇所を把握することができます。

通常は、開発プロジェクトごとに記述する内容や形式が決まっていることが多いです。

学歴、学部による「IT知識」「基礎知識」の格差を無くす個別指導の新人研修プロエンジニア育成コース(Java2・3ヶ月コース)はこちら

javadocコメントを記述しよう

javadocとは、クラス・フィールド・メソッドの説明時に使用するドキュメンテーション

コメントのことを指します。

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

自作したクラスの先頭部分には、そのクラスの概要や作成者等を

説明するコメントを書き、自作したメソッドの先頭部分には、

その処理の概要や戻り値の内容等を説明するコメントを書きましょう。

説明を記述することにより、ソースコードを読まなくてもそのクラスやメソッドの役割・機能や

使い方を把握することができます。通常は、開発プロジェクトごとに、関数の説明として記述する

内容や形式が決まっていることが多く、javadoc内では、コメントを記入する際にクラスや

メソッドの役割を示す為のタグを使用します。

​​​​​​​

特殊な変数は、用途を説明する

変数のスコープが狭い場合は、適切な変数名さえつけてあれば変数に対するコメントなどは

特に必要としませんが、例えばフィールドなど変数のスコープが広い場合、保持する値が

特殊な変数の場合は、 その用途や保持する値の内容をコメントで説明しましょう。

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

スコープが広い変数

フィールドなど、複数のクラスやメソッドから参照される変数は、どう使われ方をするのか、

どの値を保持するのかを説明しましょう。

ローカル変数はそのメソッド内のみで使用されるので、そのメソッドのソースコードを読めば

どのように使っているのかが分かります。 しかし、フィールドはまずどのクラスで使っているのか

を調べて、 該当したそれぞれのクラスのソースコードを読まないとどのように使っているのかが

分かりません。 場合によってはそれぞれのクラスがどのタイミングでどこから呼ばれるクラス

なのか、 ということまで調べないと役割が理解できないこともあります。

このような手間を少しでも軽減するため、ソースコードを読む人の理解の助けになるよう、

スコープの広い変数には説明コメントを書きましょう。

データ構造に関わるような重要な変数

プログラムでデータをどのように扱うか、その方法に大きく影響する変数には、

詳細な説明を記述しましょう。プログラムは、データを処理するためにあります。

データの集まりを保持する形式のことをデータ構造と呼び、 配列やリスト、ハッシュテーブル、

スタック、キューなど、さまざまな種類があります。 どのデータ構造を使用するかによって、

プログラムの処理の仕方に大きく影響するので、データ構造が把握できれば、そのプログラムで

どのような処理が行われているかを自ずと予想できたりすることがあります。

そのため、データ構造そのもの、もしくはそのデータ構造に関わる変数に対しては、

データの保持の仕方や保持するデータの内容などの詳細な説明を記述しましょう。

フラグのような特殊な使われ方をする変数

通常の正常でストレートなロジックを乱してしまうような、例えばフラグのような変数には、

どのように扱われる変数なのかを説明しましょう。

フラグのような変数は、プログラムのどこでどんな値を設定しているのか、 どこで参照しているの

かが分かりづらくなることがあるため、プログラムが難解になってしまいます。

そのような変数はできるだけ使用しないようにするべきですが、やむを得ず使用せざるを得ない

時もあり、どのような役割を持った変数なのか、必要であれば保持する値によってプログラムの

挙動がどう変化するのかといったことまで説明を記述しましょう。

全国の若手~ベテランエンジニアが受講している個別指導のオンライン・リモート講座(入門5日・基礎10日)資料ダウンロードはこちら

今回はソース看板、javadoc、特殊な変数のコメントについて説明しました。

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

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

■関連記事