第２章．コメントを書こう 読 み や す い プ ロ グ ラ ム を 書 く に は 、 コ メン ト を書 く こ と が 大 切 です 。 も ち ろん 、 コ メン ト が なく て も 十 分 読 み や す い プ ロ グ ラム を 書 く べ き で は あ り ます が 、 それ で も ソ ー ス コ ー ドの 要 約 や その 処 理 の 意 図 な ど を明 確 に 緑 色 の 日 本 語 の 文 字 で説 明 し て おく べ き です 。 そ うす る こ と で 、 ロ ジ ッ ク を解 析 す る 手 間 が 省 け た り 、 ソ ー ス コー ド を読 ん で も す ぐ に は 理 解 で き な いよ うな 情 報 を 読 む 人 に 伝 えた り す る こ と が で き ます 。 こ の 章 では 、 ソ ー ス コ ー ドの ど こ に 、ど の よ う なコ メ ン ト を書 く べ き か を説 明 し ます 。 ２－１．ソース看板コメントを記述しよう 各 モジュールのソースコードの先 頭 部 分 の、 package と import の間 には、ファイル名 や作 成 日 等 を記 述 するコメントを書 きましょう。 作 成 日 や変 更 日 、変 更 内 容 を記 録 することにより、ソースコードを読 まなくても修 正 箇 所 や変 更 箇 所 を 把 握 することができます。 通 常 は、開 発 現 場 ごとに、記 述 する内 容 や形 式 が決 まっていることが多 いで す。 ２－２．javadoc コメントを記述しよう javadoc とは、クラス・フィールド・メソッドの説 明 時 に使 用 するドキュメンテーションコメントのことを指 します。 自 作 したクラスの先 頭 部 分 には、そのクラスの概 要 や作 成 者 等 を説 明 するコメントを書 きましょう。 また、自 作 したメソッドの先 頭 部 分 には、その処 理 の概 要 や戻 り値 の内 容 等 を説 明 するコメントを書 きま しょう。 説 明 を記 述 することにより、ソースコードを読 まなくてもそのクラスやメソッドの役 割 ・機 能 や使 い方 を把 握 Copyright (C) 2015 株式会社 JOBSUPPORT All Rights Reserved. することができます 通 常 は、開 発 現 場 ごとに、関 数 の説 明 として記 述 する内 容 や形 式 が決 まっていること が多 いです。 javadoc 内 では、コメントを記 入 する際 にクラスやメソッドの役 割 を示 す為 のタグを使 用 します。 以下のタグは代表例です。 @version @author @param @return @throws : : : : : バージョンを記述します。 クラスやメソッドの作成者名を記述します。 メソッドの引数の説明を記述します。 メソッドの戻り値の説明を記述します。 throws がある場合、例外クラスの説明を記述します。 Copyright (C) 2015 株式会社 JOBSUPPORT All Rights Reserved. ２－３．特殊な変数は、用途を説明しよう 変 数 のスコープが狭 い場 合 は、適 切 な変 数 名 さえつけてあれば変 数 に対 するコメントなどは特 に必 要 と しません。 しかし、例 えばフィールドなど、変 数 のスコープが広 い場 合 や、保 持 する値 が特 殊 な変 数 の場 合 は、 その用 途 や保 持 する値 の内 容 をコメントで説 明 しましょう。 (1) スコープが広い変数 フィールドなど、複 数 のクラスやメソッドから参 照 される変 数 は、どのような使 われ方 をするのか、 どのよう な値 を保 持 するのかを説 明 しましょう。 ローカル変 数 はそのメソッド内 のみで使 用 されるので、そのメソッドのソースコードを読 めばどのように使 っ ているのかが分 かります。 しかし、フィールドは、まずどのクラスで使 っているのかを調 べて、 該 当 したそれ ぞれのクラスのソースコードを読 まないとどのように使 っているのかが分 かりません。 場 合 によってはそれぞ れのクラスがどのタイミングでどこから呼 ばれるクラスなのか、 ということまで調 べないと役 割 が理 解 できな いこともあります。 このような手 間 を少 しでも軽 減 するため、ソースコードを読 む人 の理 解 の助 けになるよう、スコー プの広 い 変 数 には説 明 コメントを書 きましょう。 (2) データ構造に関わるような重要な変数 プログラムでデータをどのように扱 うか、その方 法 に大 きく影 響 する変 数 には、詳 細 な説 明 を記 述 しましょ う。 プログラムは、データを処 理 するためにあります。 データの集 まりを保 持 する形 式 のことをデータ構 造 と呼 び、 配 列 やリスト、ハッシュテーブル、スタック、キ ューなど、さまざまな種 類 があります。 どのデータ構 造 を使 用 するかによって、プログラムの処 理 の仕 方 に 大 きく影 響 します。 よって、データ構 造 が把 握 できれば、そのプログラムでどのような処 理 が行 われているかを自 ずと予 想 でき たりすることがあります。 そのため、データ構 造 そのもの、もしくはそのデータ構 造 に関 わる変 数 に対 しては、 データの保 持 の仕 方 や保 持 するデータの内 容 などの詳 細 な説 明 を記 述 しましょう。 (3) フラグのような特殊な使われ方をする変数 通 常 の正 常 でストレートなロジックを乱 してしまうような、例 えばフラグのような変 数 には、 どのように扱 わ れる変 数 なのかを説 明 しましょう。 フラグのような変 数 は、プログラムのどこでどんな値 を設 定 しているのか、 どこで参 照 しているのかが分 かりづらくなることがあるため、プログラムが難 解 になってしまいます。 そのような変 数 はできるだけ使 用 し ないようにするべきですが、やむを得 ず使 用 せざるを得 ない時 もあります。 その時 は、どのような役 割 を持 った変 数 なのか、必 要 であれば保 持 する値 によって プログラムの挙 動 がどう変 化 するのかといったことま で説 明 を記 述 しましょう。 Copyright (C) 2015 株式会社 JOBSUPPORT All Rights Reserved. ２－４．ブロックの先頭に概要説明を記述しよう if や for/while、switch 等 のブロックの先 頭 には、 そのブロックで行 おうとしている処 理 の概 要 を説 明 するコメントを記 述 しましょう。 ブロックの先 頭 に説 明 を記 述 することにより、 そのブロック内 のソースコードを読 まなくてもそこで行 おうと している処 理 の概 要 が把 握 でき、 ソースコードをかいつまんで読 む際 にとても役 に立 ちます。 処 理 内 容 を要 約 するという役 割 において、コメントの効 果 は絶 大 です。 ２－５．特殊な処理、際どい処理には、理由や意図を書こう プログラムは読 みやすさを考 慮 して、できるだけ明 快 かつ自 然 な流 れで、 安 全 で安 定 した処 理 になるよ う記 述 するべきですが、 ときにはどうしても複 雑 で際 どい処 理 を書 かなければならない場 面 があります。 そのときは、後 々他 人 が、または未 来 の自 分 がそのプログラムを読 んだ時 に、 「なぜこんな複 雑 な処 理 を行 っているのだろうか？」と困 惑 してしまわないよう、 きちんと説 明 を記 述 しておく必 要 があります。 具 体 的 には、記 述 したプログラムを読 み返 したときに、以 下 のようなイレギュラーな処 理 内 容 が見 つかっ た場 合 、 その理 由 や意 図 をコメントとして記 述 しましょう。 変 則 的 な処 理 。 （例 ） 通 常 行 わなくてもいいような処 理 を、わざわざ行 っている。 不 順 な処 理 。 (例 ） 通 常 の処 理 手 順 からするとそこで行 うべきではない処 理 を、あえてそこで行 ってい る。 特 殊 な処 理 。 （例 ） データの単 純 な参 照 を行 わず、文 字 列 の部 分 切 り出 し等 の特 別 な加 工 をしてい る。 複 雑 な制 御 。 （例 ） 処 理 を行 うかどうかの制 御 や条 件 が複 雑 、または多 い。 複 雑 な処 理 。 （例 ） 複 雑 なアルゴリズムを採 用 している。 もし、コメントを記 述 しようとして説 明 内 容 を考 えたときに明 確 でもっともらしい理 由 や意 図 が思 いつかな いようであれば、 そのプログラムのロジックに問 題 があるのかもしれません。 一 度 プログラムの処 理 内 容 を見 直 し、適 切 なロジックになるようコーディングし直 してください。 Copyright (C) 2015 株式会社 JOBSUPPORT All Rights Reserved. コメントを記 述 する作 業 は、自 分 の頭 の中 を整 理 し直 す作 業 でもあります。 この処 理 は何 か？ 何 のた めの処 理 か？ なぜこの位 置 で行 っているのか？ コメントは要 るか？ というようなことを考 えることにより、 時 にはそのプログラムの不 必 要 に複 雑 になっている部 分 や無 駄 な記 述 に気 付 いたりすることがあります。 それを修 正 することで、より読 みやすくて無 駄 のないプログラムに近 づくことができます。 このように、コメントを書 くことはプログラムの保 守 性 を向 上 させ、 更 に自 身 のコーディングレベルの向 上 にもつながりますので、面 倒 くさがらず、しっかり記 述 するようにしましょう。 ２－６．処理のひとまとまりに、目印になる要約コメントを書こう プログラムは読 みやすさを考 慮 して、メソッドの処 理 が長 くなりすぎないようにメソッドを分 割 したり する必 要 がありますが、ときにはどうしても長 い処 理 を書 かなければならない場 面 があります。 そのときは、長 い処 理 の中 でも関 連 する処 理 ごとに空 行 で記 述 エリアを分 け、 そのひとまとまりに目 印 になる要 約 コメントを記 述 しておくと、長 い処 理 でもだいぶ流 れが追 いやすくなります。 以 下 に、要 約 コメントの記 述 例 を示 します。 Copyright (C) 2015 株式会社 JOBSUPPORT All Rights Reserved. Copyright (C) 2015 株式会社 JOBSUPPORT All Rights Reserved. 目立つコメントは、書きすぎに注意 上 述 のように目 印 になるような目 立 つコメントは、 要 所 要 所 に記 述 すると長 いプログラムの処 理 が追 い やすくなってとても役 に立 ちますが、 記 述 する際 は書 きすぎないように注 意 してください。 本 当 はそれほど長 くない処 理 だったり目 立 たせる必 要 がなかったりする場 面 で、 何 でもかんでも目 立 つ コメントを書 いてしまうと、 処 理 の記 述 が埋 もれてしまい逆 に読 みづらくなってしまうことがあります。 また、コメントに頼 りすぎず、「うまくメソッド分 割 ができないか？」等 、簡 潔 に記 述 する方 法 もきちんと検 討 しましょう。 ２－７．無駄なことを書かず、プログラムの理解を助けるためのコメントを書こう コメントには、当 たり前 すぎることは書 かず、プログラムを読 む人 の理 解 を助 けるための説 明 を記 述 しまし ょう。 日 本 語 での説 明 のほうが分 かりやすいからと言 って、全 ての処 理 一 行 一 行 に対 してコメントを書 く必 要 は ありません。 何 でもかんでもコメントを記 述 すると、処 理 の部 分 が埋 もれてしまい、逆 に読 みづらくなります。 また、本 当 に注 目 すべき説 明 文 が目 立 たなくなってしまい、 せっかく書 いた注 釈 としてのコメントの効 果 が 薄 くなってしまうこともあります。 コメントを記 述 する際 は、そのソースコードを他 人 が読 んだ時 にすんなり理 解 できるか？ そのままでは誤 解 や混 乱 を招 いてしまうようなロジックになっていないか？ というようなことを考 え、 コメントの要 ／不 要 を 判 断 するようにしてください。 当 たり前 すぎて説 明 する必 要 のない処 理 にまでコメントを書 く必 要 はありません。 「これは説 明 しておか ないとコードを見 てもすぐには理 解 できないだろう」と思 われる箇 所 にコメントを書 きましょう 。 Copyright (C) 2015 株式会社 JOBSUPPORT All Rights Reserved. Copyright (C) 2015 株式会社 JOBSUPPORT All Rights Reserved.
© Copyright 2024 Paperzz
