 |
|
|
| 前のページ 1 2 3 4
|
|
| その他のフォーマットに関する規約
|
こまかな記号の規約は覚えるのも大変で、逆に作業効率を落とすことにもなりかねません。開発ツールの機能と照らし合わせて、うまく規約を作成しましょう。
|
| return文ではカッコを使わない（C_FMT013）
|
return文では、不要なカッコは使用しないようにしてください。Javaの仕様上、returnできるオブジェクトは1つだけです。カッコを使用するとreturn文を何らかのメソッドと見間違えてしまうなど、可読性の低下につながる可能性があります。
なお、return文でカッコを使って演算している場合は、事前に演算を済ませてください。
|
| boolean変数は既に比較済み（C_FMT014）
|
boolean変数をわざわざtrueと比較していませんか。boolean変数は比較するまでもなく、それ自体が条件の結果を表していますので、これをtrueと比較する記述は冗長です。
|
| 不等号の向きは左向き（"<"、"<="）にする（C_FMT015）
|
不等号の向きがばらばらになっている場合は、不等号の向きを統一することでコードが読みやすくなります。以下に示す例外を除いて、向きは左向きに統一してください。
- 定数との比較時には、定数を常に右側におくことで可読性がよくなることがあります
- 演算の中心となってコードに何度も現われる変数は、変数を常に左側に置くことで可読性がよくなることがあります
|
表5：不等号の向き
|
これらのフォーマットに関する規約に関しては、「絶対にこうでなければならない」といった性質のものではありませんので、プロジェクトによっては異なった規約を適応してもよいと思います。ちなみに、プロジェクトごとに異なった規約を適応すると「すべての規約を覚えきれない」ということになりがちですが、Eclipseなどの開発ツールを使うとフォーマットに関する規約を設定することができますので、ぜひ活用してみてください。
|
| コメント
|
コメントは単にソースコードのメモ書きとしてだけではなく、ドキュメントの作成にもつながります。コメントにどのような内容を書くのかをプロジェクト内で定義しておけば、ドキュメントもしっかりとしたものが作成できます。
|
| Javadocコメントには、少なくともauthorとversion（クラス）、paramとreturnとexception(メソッド)を記述する（C_CMT001）
|
Java SDKには、Javadocというドキュメント自動生成ツールが付属しています。Javadocツールを実行すると、ソースコード中の宣言やJavadocコメントを解析し、自動的にHTML形式のAPIドキュメントを作成します。
クラス、メソッド、フィールドについては下記のようにJavadocコメントを記述してください。特にpublic及びデフォルトで宣言されたものについては必須です。下記以外のタグについても、必要に応じて記述してください。
- 「⁄**」で始める
- 2行目以降は「*」で始め、下記のJavadoc タグで本文を記述する
- 「*⁄」で終わる
|
表6：Javadocコメントの様式
|
- @author [作成者]
- クラスの作成者及び更新者を記述する。複数記述する場合は1人ずつタグを記述する。
- @version [バージョン]
- クラスのバージョンを記述する。
|
表7：タグのコメント
|
- @param [名前]、 [説明]
- パラメータの名前とその説明を宣言されている順に記述する。
- @return [説明]
- 返り値があれば、返り値の説明を記述する。
- @exception [名前] 、[説明]
- メソッドが呼ばれた際にthrowされる可能性のある例外名とその説明を記述する。
|
表8：メソッドのコメント
|
- フィールド
- できるだけ変数名で説明する。どうして表しきれない場合は、Javadoc コメントとして説明を記述する。
|
表9：フィールドのコメント
|
Java以外の言語では標準のドキュメント生成ツールが存在しないことが多く、APIドキュメントの作成に多くの時間が取られることがありますが、JavaではJavadocツールが標準のSDKで提供されているため、APIドキュメント作成の手間がかなり軽減されます。
このように便利なツールですが、コード中にJavadocコメントの記入がなければ意味がありません。Javadocツールを有効に利用するために、Javadocコメントにどのような内容を記述するのかについて、プロジェクトできちんと定義するようにしてください。
CVSなどのバージョン管理ツールを利用している場合は、authorタグとversionタグに記述する内容をバージョン管理ツールの書式に合わせて記述することによって、リビジョンとJavadocの連携が取れます。
|
| コメントは必要なものだけを簡潔に（C_CMT002）
|
必要以上にコメントを書くと修正しにくくなります。そのために「コメントは必要なものだけを簡潔に」記述します。
よくある例としては、「コードの修正を行った際は、修正前のコードと修正者、修正内容をすべてコメントとして記述する」というルールを設けているケースがあげられます。しかし、実際にこのルールにしたがってすべての修正履歴をコメントに残すと、あまりにも修正履歴が多くなりすぎて、コードの可読性を大幅に下げてしまうことになりがちです。
このような場合はCVSのようなバージョン管理ツールを導入して、修正履歴はバージョン管理システムで管理し、ソースコードには最終的に必要なコメントのみを残すようにしてください。
なお、プロジェクトの成果物として、詳細設計書のかわりにJavaDocドキュメントを提出するように規定されているプロジェクトがあると思います。このようにコメントを設計書として利用する際には、通常より詳細なコメントを記述する必要があります。
どこまでコメントを記述するかはプロジェクトによって異なりますので、コーディングに入る前にコメントのガイドラインをプロジェクトで決定しておくことが重要です。
|
| まとめ
|
本連載で紹介したメトリクス、フォーマット、コメントの規約は「単純な決めごと」といえますが、これほど細かく規約を決めていないプロジェクトも多いのではないでしょうか。
しかしこれらの決めごとを統一することによって、チーム内で他人の書いたソースコードの可読性の向上が期待できます。これは空白文字やインデントをほとんど使用していない極めて読みにくいソースコードを保守した経験のある方ならおわかりだと思います。
また、フォーマットなどの規約があると、コードの書き方に関する細かい決まりごとに関して、プログラマ自身が悩んで時間を費やすことがなくなります。つまり、プログラマがコーディング作業に集中することができ、コーディングの効率や品質の向上につながります。
現在は、幸い開発ツールの機能の充実により、単純作業の手間はますます開発ツールに肩代わりさせられるようになってきました。こういったフォーマットに関する規約は開発ツールに任せることも有効だと思います。
なお、本連載の規約の中には、インターフェースやfinalの利用など、設計の思想やオブジェクト指向言語に特有の規約が含まれています。これらの規約については、最初のうちはなかなかその必要性を理解できないかもしれませんが、仕様変更に強いプログラムを作るうえでのよいヒントが含まれています。
今までオブジェクト指向設計に関してあまり意識をしていなかった方も、これを機会にオブジェクト指向設計に興味を持っていただければ幸いです。
|
前のページ 1 2 3 4
|
|
|
|
|
著者プロフィール
株式会社電通国際情報サービス 高安 厚思
株式会社電通国際情報サービス 開発技術センター
Java（J2EE）／オブジェクト指向の研究開発やプロジェクト支援、開発コンサルティングに従事。モデル、アーキテクチャ、プロセスが探求対象。今回は Javaコーディング規約2004の仕掛け人。
|
|
著者プロフィール
株式会社電通国際情報サービス 東田 健宏
株式会社電通国際情報サービス 開発技術センター
CTI、Webアプリの開発経験を経て、現在は主にプロジェクトマネジメント支援、プロセスエンジニアリング、ソフトウェア工学研究開発に従事。最近はコーチング、ファシリテーションといったヒューマン系スキルに興味を持ち日々修得に努めている。
|
|
著者プロフィール
インクステクニカルサービス株式会社 桐山 邦彦
インクステクニカルサービス株式会社 システム開発部所属
J2EEのリリース時から今日まで、主にWebアプリの開発に従事。他人から引き継いだコードのメンテナンス作業も多く、その保守性の低さをたびたび経験し、オブジェクト指向設計に強い関心を抱くようになる。
|
|
|
|
|
|
