💭

適切な命名を意識する

Kojiro Ohara2023/01/25に公開

TL;DR

  • 開発したコードは後に1000回参照されることを意識して、意味の理解できる命名を行う。
  • 業務個別の名称は用語辞書を作成する。

残念な命名

具体的な例をいくつか見ていきましょう。

truefalseの意味が理解できないboolean

画面のチェックボックスのチェックの有無でふるまいを変える処理です。

boolean chkFlg = false;
for (SendForm sendForm : form.getSendFormList()) {
  if (sendForm.isItemChecked()) {
    // チェックありの場合、true。1件でもチェックありだったら処理を抜ける
    chkFlg = true;
    break;
  }
}
// chkFlgがfalseだったらエラー
if (!chkFlg) {
  param.setMsgInfo(new MessageInfo(MessageCd.A1001E, "選択チェック"));
  param.setResultCd(ResultCd.ERROR);
  return;
}

chkFlgfalseだったらエラー」とコメントしないといけない時点でよくない命名なのがわかります。

このフラグに命名するなら、

  • checkedItemExists チェックされたものが存在する。
  • hasCheckedItem チェックされたものを保持している。

これであれば、falseのときはチェックが入っていないのだなと理解できるでしょう。

チェックされている」という状態はどういうことなのかという観点で命名することもできると思います。

たとえば、isDestinationSet(送信先が指定されている)など。

定数化の意味がわかっていない

判定処理に利用する文字列を定数化しているものです。

private static final String DB_STR50 = "50";
private static final String DB_STR1 = "1";
private static final String DB_STR2 = "2";

// foo区分が50以下ならBAR番号を利用する。個人団体区分を個人にする。
if (DB_STR50.compareTo(fooKbn) >= 0) {
  keiyakuNo = baz.getBarNum();
  kojinDantaiKbn = DB_STR1;
} else {
  // foo区分が51以上ならQUX番号を利用する。
  keiyakuNo = baz.getQuxNum();
  // THUDコードを判定し、個人団体区分を設定する。
  if (DB_STR1.equals(contract.getThudCode().substring(3,   4))) {
    kojinDantaiKbn = DB_STR1;
  } else {
    kojinDantaiKbn = DB_STR2;
  }
}

DB_STR50という名称は何も意味をなしていません。
50、1、2という謎の情報はコメントを入れることでかろうじて理解できそうです。
どんなことに利用するのかが理解できる名称に変更する必要があります。

private static final String KBN_KOJINHANTEI_THRESHOLD = "50";
private static final String KBN_KOJIN = "1";
private static final String KBN_DANTAI = "2";

また、クラスにprivate定義するのではなく共通で利用する定数クラスを作成すると個々の開発者のブレが紛れ込まないよい方法です。

用語が統一されていない

ひとつのプロジェクト内で次のような変数名がありました。

  • CustomerNo
  • KoNo
  • KokyakuNumber

すべて顧客番号を意味しています。
これは実装者がそれぞれの解釈で命名をしたことによります。
どれを選ぶのが適切だったでしょうか。

ここではKoNoが適切でした。

ユーザーが用意したデータモデルでは顧客番号をKoNoと定義していたためです。
このような事態にならないように、事前に用語辞書を整理しておくことを推奨します。

標準的な命名

Javaを例に標準的な命名ルールを確認します。
Googleの規約から引用したものですが、よほど特殊な現場ではない限り適用できます。

参考:Google Java Style Guide

すべての言語には同様な命名ルールが存在します。
業務で適用する際には事前に確認するとよいでしょう。

共通ルール

識別子はASCII文字、数字のみを使います。(例外としてアンダースコアを利用します。対象は後述)

パッケージ名

パッケージ名はすべて小文字で連続する単語をそのまま繋げます。

例:com.example.deepspace

クラス名

クラス名は大文字キャメルケース(UpperCamelCase)の名詞で命名します。

例:StringUtility

テストクラスはテスト対象クラス名で始まり、 Testで終わるよう命名します。

例:StringUtilityTest

メソッド名

メソッド名は、小文字キャメルケース(lowerCamelCase)で命名します。
必ず動詞から始まります。

例:sendMessage

定数フィールド名

定数(static finalのフィールド)はコンスタントケース(CONSTANT_CASE)の名詞で命名します。
大文字の名詞をアンダースコアで結合します。

定数でないフィールド名

定数でないフィールド名は小文字キャメルケース(lowerCamelCase)名詞で命名します。

パラメータ名

パラメータ名は小文字キャメルケース(lowerCamelCase)で命名します。
一文字のパラメータ名はpublicなメソッドでは避けます。

ローカル変数名

ローカル変数名は小文字キャメルケース(lowerCamelCase)名詞で命名します。

現場のコーディング規約を確認する

SIの現場ではユーザーがコーディング規約等を用意しています。
まずは現場のルールに従いましょう。

まとめ

  • コードは後に1000回読まれることを意識して、意味のある命名をする
  • 業務に関連する用語はデータモデルから用語辞書を確認し、統一された命名を行う
  • 用語辞書がなければ整理する
  • どの言語にも標準的な命名ルールがあるので、知識として各自学習する
  • コーディング規約の有無を確認し、それに従う

Discussion

ログインするとコメントできます