1. 今回お話しすること
- 「メンテナンスしやすいコード」という軸でまとめたよ
- 前回の続きだよ
- 今回は「変数やメソッドの名称」の話に絞って、具体的なテクニックを紹介するよ
- Javaやjavascriptコードで説明を書くけど、全言語共通で使えるテクニックだよ
- 私個人の考えなので、「いいな」と思うものだけピックアップしてもらえたら何よりです
2. 雑談
前回「メンテナンスしやすいコードを書こう（その１）」の記事に対し、とても多くの意見をいただきました。ありがとうございます！
少し個人的な話になりますが、私は今の会社に新卒入社して6年目、30歳の若手エンジニアです。大学や大学院では化学が専攻だったため、プログラミング歴はほぼ入社歴と同じです。私なりに今の正解を綴っているつもりですが、まだまだ井の中の蛙感が拭えません。内容の誤りや、よりよい方法、また違った視点などをコメントいただけるととても勉強になります。是非お願いします。
3. テクニック集
3.1. メソッドや変数の名前には中学レベル以上の英語は使わない
プログラミングで使う文字はアルファベットが基本ですので、やはり英単語を使う方が違和感がありません。
ですが英単語を使わ「ないと」と思っていると、メンテナンスしにくいコードになることがあります。
例えば、以下のような意味を持つ変数に名前を付けるとしたら、どんな名前にするでしょうか。
業務報告書をあらわすクラスを考えます。
- 「報告書作成日」を示す変数名
- 「業務実施日」を示す変数名
- 「上司確認／決裁日」を示す変数名（複数の上司がいる想定で正規化・・・とかここでは考えずに）
もちろん、100点の正解はありません。
ちなみに単純にgoogle翻訳さんで英語に直してみると・・・
- 報告書作成日：Report creation date
- 業務実施日 ：Business Implementation Date
- 上司確認日 ：Boss confirmation date／Resolved date of the boss
となりました。
・・・
僕ならこんな感じにすると思います。
- 報告書作成日： date_created／dateCreated
- 業務実施日 ： date_jisshi／dateJisshi
- 上司確認日 ： date_kakunin／dateKakunin
Implementationという英単語は中学では使わないでしょう。（今回は一応このサイトで英単語を見てみました。）これを一目で「実施」と読めない人は、プロジェクトメンバーにもいるはずです。あまりに制限しすぎると「わかる人」が作りづらくなりますし、とはいえそうでない人にもっと英単語勉強せいやと言っても難しいところもあるかと思います。その折衷案が「だいたい中学英語まで」という話です。もちろん、難しい単語であっても、その業界などでよく使われているものであれば、使ってしまったほうがいいと思います。
ちなみに安易に連番などを名称にいれることもお勧めしません（date_01とか）。膨大な数の変数名を決めなければならず、かつ連番を振っても違和感がないくらい密接な関係性のあるもの同士なら許容しますが、そうでない場合は後で見た時に「この変数はどんな意味なのか」が追いづらくなります。（コメントで見たらある程度分かりますが、逆に言えばコメントをわざわざ見ないとわかりません。）
3.2. 2単語以上の名前の場合、順番を意識しよう
3.1の節で、私が考える変数名は「date_XXX」としていました。この節では、ここで"date"を前に持ってくるのか、後ろに持ってくるのか、という話をしようと思います。この答えももちろん、時と場合によります。なので、僕が指針として持っている考え方について触れたいと思います。
まず私の中で一番軸になっているのは、「将来ありうる改良を想像したときどの単位でまとまっていると見やすい／わかりやすいのか」です。3.1節の例で考えてみましょう。
今回の例では『「日付でソートがかけたいな。日付は日付なんだけど、このオブジェクトってどんな日付持ってたかな？何でソートするのが使いやすいかな』」という感じで考える将来の改良を想像しました。逆に、『報告書作成日はすでにあるけど、作成者も追加したいな。あ、業務実施者もほしいし、決裁者もほしい！』という改良も想像できますよね。そうなったときには、逆にcreate_XXXやjisseki_XXXという軸でまとまっていたほうが使いやすいかもしれません。
これについては明確な正解はないですが、まったく考えないのも悪ですね、くらいの注意喚起としてとらえてください。この命名を決めるのに2時間3時間かけるのは時間の無駄だと思います。
3.3. 中身に合った名称にしよう
みなさん、以下のメソッド名を見たときに、どんなメソッドを想像しますか？
ちなみに初めて出てきた int categoryIdは、多数あるItemを分類分けするためのカテゴリのキー値だと思ってください。そしてItem一覧が表示されるwebの画面上に「カテゴリ」というプルダウンがあり、そこを変更するとそのカテゴリのItem一覧に絞って再表示するような画面のロジック処理の一部を想像してください。
public static List<String> getListItemTitle(int categoryId) {
// 処理内容
}
「DBアクセスして、categoryIdをキーにItemのリストを取得してくるんだろうなー」とか、「すでにオブジェクトとして取得済みのItemListから、該当のcategoryIdのものだけを抽出してくれるのかなー」とか、そんな感じのことを想像すると思います。
でも実はこのメソッド内では、そのような一覧取得のSELECTのほか、「このユーザがこのカテゴリIDで検索した、という検索履歴テーブルにINSERTを走らせています。」と聞いたらどうですか？「え？DB更新してんの？！」となりませんか？
たしかに、カテゴリで絞ってSELECTをかけたときに、かならず履歴の登録とペアで実行したいという要件はあると思います。でもそうであれば、メソッド名のどこかで、INSERTもしているよとわかる名称にすべきです。名称をみただけである程度の大枠で何をしているメソッドかわかる状態にしておかないと、将来の改良で意図せず再利用して変なDBレコードができあがることになりかねません。
「そうするとメソッド名長くなるよね？」とも思いますが、「短くしたいがために重要な情報を持っていない」名称になるよりかは、「必要十分な情報が入っているが長い」名称の方がよっぽどメンテナンスしやすいです。とはいえ100文字200文字を許容したいわけではないので、節度は大事ですけどね。
次回も名称関連の話を続けようと思います。