catch-img

新人SE・PG教育にも使える!ソースコード(Java)のコメントの書き方①

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

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

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

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

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

■関連記事

  新人SE・PG教育にも使える!見やすいソースコード(Java)の書き方① | 株式会社ジョブサポート-新人研修・未経験者向けエンジニア研修(Java,JavaScript)のジョブサポート ジョブサポートではエンジニアのプロとして活躍する土台として、見やすいJavaのソースコードの書き方を早い段階から徹底して指導しています。ただ動くプログラムを書くのではエンジニアの技術面の成長を妨げてしまいます。 株式会社ジョブサポート-新人研修・未経験者向けエンジニア研修(Java,JavaScript)のジョブサポート


目次[非表示]

  1. 1.読みやすいプログラムを書くには、コメントを書くことが大切
  2. 2.ソース看板コメントを記述
  3. 3.javadocコメントを記述しよう
  4. 4.特殊な変数は、用途を説明する
    1. 4.1.スコープが広い変数
    2. 4.2.データ構造に関わるような重要な変数
    3. 4.3.フラグのような特殊な使われ方をする変数

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

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

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

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

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

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

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

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

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

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

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

短期講座(Java入門5日・基礎10日)ー株式会社ジョブサポート


javadocコメントを記述しよう


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

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


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

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

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


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

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

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

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


​​​​​​​

プロエンジニア育成コース(1~3ヶ月コース)ー株式会社ジョブサポート

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


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

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

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


スコープが広い変数

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

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

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

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

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

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

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

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

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


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

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

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


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

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

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

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

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

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


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

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

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

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

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

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

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

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


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

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

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

オンライン・リモート講座(入門5日・基礎10日)ー株式会社ジョブサポート

■関連記事

  ソースコード(Java)のコメントの書き方② | Web開発・エンジニア研修(Java・フロントエンド)なら株式会社ジョブサポート 今回は2回目の内容なので1回目を読んでからだと内容の理解が深まると思います。ジョブサポートのエンジニア研修ではJavaのプログラムを例にコメントがなぜ必要なのかを早い段階から学び、習慣付けていきます。 Web開発・エンジニア研修(Java・フロントエンド)なら株式会社ジョブサポート


通年でJava研修(オンライン・リモート研修も可)の受け入れを行っており、助成金を活用すれば

費用負担を軽減して研修受講ができるのでお気軽にお問い合わせ下さい。




下記フォームを入力して

資料(全12P)を見る

職場で使用されているアドレスをご記入下さい。

アップロードしています。少々お待ちください。