Skip to end of metadata
Go to start of metadata

目次

コードベースは意識してキレイに保っていく必要があります。割れ窓理論Wikipedia, はてなキーワード)を意識しましょう。駅前に自転車を駐輪していた場合、前カゴに1つでもゴミが入っていると、たちまち道行く人のゴミ捨て場と化すという、アレです。

Javaコーディングスタイル

ある程度までは自動コードフォーマッタに任せるようになっていますが、一応。以下の2規約をベースに、特に重要な項目や相違点をまとめていく。

コードフォーマッタ

基本的にコードフォーマッタ及びEclipse・Checkstyle・FindBugsの警告に従う。

  • EclipseのSave Actionにて、保存時にコードが自動整形される。
  • 多少見づらいフォーマッティングをされる事がもあるが、属人性排除の為、とにかくフォーマッタに従う。
  • コメントのコードフォーマットは行わない。記述方法に関しては後述。

インデントと体裁

本項は、フォーマッタで自動整形されるので、あまり気にしなくてよい。

Tab幅は4で、インデントには全てTabを使用する。

Tabを使用せずにSpaceを使う、というのが一般的な方針かもしれません。しかし、Eclipseでの開発が前提であるため、環境に依存したタブ幅による表示崩れが想定されません。従って、Jiemamy ProjectではインデントにTabを使用することとします。

1行最大120文字とする。

80文字は時代遅れだと思っている。いまどき、プリントアウトは無いでしょうからw ただ、画面解像度の問題があるので、100程度にすることも検討の余地あり。意見求む。

Java言語

省略できるコードは、特別な意図がない限り書かない。例えば…

  • コンストラクタが1つしか無い場合の、空のデフォルトコンストラクタ
  • コンストラクタ内での明示的な引数無しsuperの呼び出し
  • インターフェイスに定義するメソッドのpublic, abstract修飾子
  • インターフェイスに定義するフィールドのpublic, static, final修飾子
  • ローカル変数と名前がかぶらない場所での、フィールドを表すthis
  • throws句のRuntimeException
  • など

final修飾子は、特別な意図がない限り使わない。つまり、単純に二度代入されないローカル変数等にはつけない。使っても良いのは、例えば…

  • 無名クラス内から参照するケース(これは必要なfinal。なければコンパイルを通せない)
  • イミュータブルクラスを作る際、イミュータブルを担保するためのフィールドやクラスのfinal
  • イミュータブルクラスではなくても、コンストラクタで受け取った後にインスタンスが差し変わらないフィールドのfinal

比較演算子(==, <, >, <=, >=)は、基本的に「左辺を actual、右辺を expected」とする。

  • if (x == 3) とする。if (3 == x) とはしない。
    & if (str.equals("foo") とする。if ("foo".equals(str)) とはしない。
  • 例外的に、xは1以上10以下を表現する場合は if(1 < x && x <= 10) とする。

否定演算子("!")は使わな い。("!=" はOK)

  • if(!foo) ではなく if(foo == false) とする。
  • ↑見ると分かるが、見落とし易いので。

テストクラス

テストのアサーションは全て assertThat を使用する。

テストメソッドの命名規則は基本的に以下の例のように。

01, 02とか、あんま良いアイデアだとは感じていないけど、コードフォーマットでメソッド順が入れ替わるので…。ディレクトリやパッケージ毎にフォーマットの設定を変えられればいいのだが…。

Mockオブジェクトを利用する際は、Mockitoを利用すること。

XMLコーディングスタイル

インデントと体裁

Tab幅は2で、インデントには全て半角スペースを使用する。

1行最大120文字とする。

80文字は時代遅れだと思っている。いまどき、プリントアウトは無いでしょうからw ただ、画面解像度の問題があるので、100程度にすることも検討の余地あり。意見求む。

命名規則

識別子名

  • ローマ字禁止。必ず英語を使う。テストコードに限り、マルチバイト(日本語)のメソッド名を使用する。やはりローマ字は禁止。
  • 型の名前は基本的に名詞。メソッドの名前は基本的に動詞(で始まる)。
  • 基本的に(リスティングしたもの以外全て)単語は省略しない。(電通N_LVL001と矛盾)
    • 名前が長くなってしまう傾向があるが、とにかく省略しない。(そのために1行を長くしている、というのもある)
  • インターフェイスのprefix「I」(アイ)は使用しない。(電通 N_CLS003を修正)
    • interfaceはprefix無しとする。実装クラスのsuffixにImplを使用するのは構わない。
    • インターフェイスに対して複数の実装クラスがあるのであれば、それぞれに適切な名前が付けられるはずなので、Implも使用しない。
    • 型を扱う際、この型が「インターフェイスなのかクラスなのか」を意識すべきではないと考えている。
    • そして、できる限りインターフェイスで型を扱わせたい。Implがついた型の変数宣言は気持ち悪い。この心理を利用しているw
  • コレクション・配列の変数名に関しては、基本的に複数形の名詞を使用する。
    • fooの配列とfooのコレクション等、foosと命名すべきものが複数存在する場合は、配列を「foos」とし、その他を「fooList」「fooSet」等とする。
  • fieldと同名のlocal変数は使用可とする。アンスコprefixは基本禁止。(電通N_PRM001と矛盾)
    • Eclipse前提なので、シンタックスカラーリングで判断できる。
  • 大文字単語(SQL, ID, DNS等)を識別子名に使用する場合、命名は例えば「SQLManager」ではなく「SqlManager」とする。
    • 個人的に前者の方が美しいとは思うのだが、そのクラスをインスタンス化した時の識別子名としてはsQLManagerではなくsqlManagerになるであろう。
    • そして、それのgetterを考え得ると、仕様上 getSQLManager ではなく getSqlManager になる。
    • これに一致させた方がいいのではないか、という意図。この方がロジックで変換が可能でしょ。
  • ユーティリティクラスのsuffixは Utils ではなく Util とする。

パッケージ名

  • ベースパッケージ名はorg.jiemamyとする。
    • eclipseに依存するコンポーネントは、その直後にeclipseをつける。

ドキュメンテーションコメント(Javadoc)

  • 文体は日本語で、「だ、である調」で統一する。
  • 受動態は極力避ける。
  • クラスのJavadocは「何なのか」の説明。何をするか、ではない。これに対して、メソッドのJavadocは「何をするか」の説明。
  • 仕様は可能な限り一般論で記述。ただし、複雑な場合はドキュメンテーションの最後に、補足として「例示」を入れるとGood。
    • あくまでも補足であるのに注意。補足が無くても挙動の定義ができているように。
  • 「国語辞典にある単語」「技術書で一般的に使われている単語」でない限り、その語をきちんと説明することが大事。
    • 自分達でつけた名前の定義は、どこでも通用するものではない。「"JavaClassName" とはいったいどんな "名前" なのか」とか。
    • 抽象的な語は、具体的に説明。「修飾する」では曖昧。「どのような修飾をするのか」とか。
  • メソッドの説明は、「シグネチャとjavadoc」を読めば実装が1から書けるだけの情報を盛り込むことを意識する。
    • 仮に、事故でメソッドの実装部分が丸々消えてしまったとしても、シグネチャとjavadocさえあれば、元と同じ仕様のメソッドを復活できるような情報。
  • 1行目は主説明とし、ドキュメンテーション対象を一言で説明する一文を記述する。行末は「。」で締める。pタグでは囲まない。
  • 詳細説明は、主説明の後に1行あけて、段落ごとに。pタグで囲む。pタグが複数あっても良いが、それぞれの間は1行あける。
  • 説明内のクラス名には、{@link} によるリンクを入れる。
  • 説明内の変数名(引数名など)には、基本的に {@code} を使用する。
    • 複数行にまたがるcode要素には<code></code>を使わざるを得ないので、遠慮無く使う。
  • 説明部とJavadocタグ部の間は1行あける。
  • 各Javadocタグの末尾は、基本的に句点(。)で締めない。ただし、2文以上の記述をする場合は句点で締めてよい。
  • @throws は、チェック例外はもちろんのこと、RuntimeExceptionに関しても明記し、行末は「~場合」で締める。
    • "@NullArgumentException" で「@throws IllegalArgumentException 引数に{@code null}を与えた場合」がEclipse補完可能。
  • 戻り値が null の可能性がわずかにでもある場合は、どんな時に null を返すのか@returnsに明記する。
  • 戻り値booleanに関しては、@return タグにて「~の時{@code true}、そうでない場合{@code false}」で締める。
    • "@returnsBoolean" で「@return 場合は{@code true}、そうでない場合は{@code false}」がEclipse補完可能。
  • 型Javadocには、@version $Id$ を必ず記載する。
  • 型Javadocには、@author ... を必ず記載する。
  • @sinceタグによって「公開APIであること」のマーキングをする。@sinceタグのついた対象の仕様を変更してはならない。
    • 公開APIとして扱う型自身、及びそのpublic, protectedメンバーのJavadocには、@sinceを必ず記載する。
    • publicではあるが公開としない型には記載しない。(ただし本文中に非公開であることを明記する。)
    • publicで公開する型だが、package private, privateなメンバには記載しない。

accessorのJavadocについて

例は上の通り [ほげふが] が全部一致してるのがポイント。

メトリクス

外部化メッセージ

  • 外部化メッセージにアクセスするクラスはパッケージ単位に用意するものとし、アクセス修飾子が default で NLS クラスを継承したクラス名 Messages とする。
    • ただし、プロジェクト単位で共通化する外部化メッセージの場合は、プロジェクトのトップパッケージにおいてアクセス修飾子 public で NLS クラスを継承したクラス名 CommonMessages とする。
  • 外部化メッセージを保持する properties ファイル名は messages.properties とし、作成するロケールに合わせて messages_ja.properties のようにする。
    • ただし、プロジェクト単位で共通化する外部化メッセージの場合は、この限りではない。
  • フィールド名の命名規則
    • 該当する外部化メッセージを利用するクラス名を接頭辞とし、その後に固有のフィールド名をつける。
    • パッケージ単位の外部化メッセージである場合、接頭辞は特につけなくてもよい。
    • プロジェクト単位の外部化メッセージである場合、接頭辞は Common とする。
コード例

その他

  • auto-boxing / unboxingは使用可能。
    • ただし、ちゃんと意識した上で使うこと。何も考えずに使わない。
  • serialVersionUIDに対しては、現状は @SupressWarnings で対応する。
  • 拡張for構文は積極的に利用する。

Eclipse設定ファイルについて

  • Eclipse設定ファイル(以下、dotファイルと呼ぶ。/.settings等も。)も一緒にコミットする。
  • ただし、その設定に「開発環境に依存する設定」を含まないこと。例えば、「絶対パス」などを含んではいけない。
  • 同様の理由で、設定に「ワークスペースデフォルト」を使用しない。
    • プロジェクトに対するEclipseの設定には「ワークスペースデフォルト」(Window > Preferencesから設定する項目)を参照するように設定することができるが、Preferencesの設定は各開発者で同じであるとは限らない。
    • 例えば.classpath に設定する「JRE System Library」について。
      • この設定が「ワークスペースデフォルト」になっていて、開発者Aの環境ではJava6が設定されていたとする。Aがコミットしたファイルには interfaceの実装メソッドに@Overrideがついていたりする。
      • 次に、開発者Bの環境ではJava5がデフォルトだったする。Bがプロジェクトをチェックアウトすると、Java5でコンパイルされるので、@Override部分にエラーが起きてしまう。(さらに、「@Overrideが付けられるところに自動でつける」というコードフォーマッタがついていますので、2人でコミット合戦になってしまいますね)
    • その他、コンパイラが警告する内容の詳細設定(これは警告して、これは警告しない等)や、コードフォーマッタ等、「ワークスペースデフォルトが設定できるもの」は、全て「プロジェクト固有の設定」をしっかり設定して行く(自分のワークスペースデフォルトであっても、他の開発者のデフォルトであるとは限らない)という方針です。ご協力お願いします。
  • 何が変わったのかを理解せずにdotファイルをコミットしないのが大事です。コミット前にはdiffを取って、dotファイルに変更があるかどうか? あるならば、その変更内容を自分が理解しているかどうかを確認してください。

コンパイラレベルの設定の例

これがPreferece(グローバルな設定で、開発者毎に異なる可能性があり、プロジェクト内に設定ファイルがないのでコミットもできない)。
Window > Preferences によりこのページを開く事ができる。

これがプロジェクトのProjectの設定(プロジェクト単位の設定の設定。dotファイルをコミットする事により、設定を共有できる)。
プロジェクトを右クリックして、コンテキストメニューの最下段 Properties により、このページを開くことができる。

上の網掛けで示した部分にチェックが入っていないと、Preferenceの値(ワークスペースデフォルト)が使用されてしまう。

使用するJREの設定の例

これがPreferece(ワークスペースデフォルト)

これがプロジェクトのProjectの設定(プロジェクト固有で、dotファイルとしてコミット可能)

網掛けした項目のどちらかを選択しない限り、ワークスペースデフォルトが使用される。
ちなみに、Alternative JREの方は「Java 1.5.0_14」と、ピンポイントで指定する設定。Execution Environmentは「まぁ、Java5で」という感じで、ザックリと指定する設定です。


null
Labels
  • None