catch-img

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

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

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

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

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

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

ジョブサポートのエンジニア研修ではコメントについても研修中から指導していきます。

今回Javaのソースコードのどこに、どのようなコメントを書くべきかを2回に分けて記載します。


目次[非表示]

  1. 1.ソース看板コメントを記述
  2. 2.javadocコメントを記述しよう
  3. 3.特殊な変数は、用途を説明する
    1. 3.1.スコープが広い変数
    2. 3.2.データ構造に関わるような重要な変数
    3. 3.3.フラグのような特殊な使われ方をする変数


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


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

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

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

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

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



javadocコメントを記述しよう


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

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


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

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

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


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

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

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

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


​​​​​​​

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


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

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

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


スコープが広い変数


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

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

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

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

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

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

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

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

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


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


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

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


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

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

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

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

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

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


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


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

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

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

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

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

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

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


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

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

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



お問い合わせ

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