記事の内容
この記事はフリュー Advent Calendar 2024の15日目の記事となります。
ずっとインフラ周りの業務を担当していたのですが、最近SpringBootを使って「お問い合わせツール」の開発業務に携わることなりました。そこで、命名の大切さをいろんなシーンで感じたので、記事にまとめてみました。
命名の大切さを感じたシーン
- データベースのテーブル設計をしてみて
- APIのURL設計をしてみて
- O'reillyのリーダブルコードを読んでみて
データベースのテーブル設計をしてみて
弊社は、Webサービスやゲーム、筐体など数多くのサービスをお客様に提供しています。お問い合わせツールを作成するにあたって、問い合わせをサービスごとに分類する必要があります。そのためサービスを管理するテーブル名を何にするか定義する必要がありました。まずはテーブル名を検討するのですが、サービスなのでServicesでいいなとすぐ決めました。しかし、実装を進めていく中で、お客様に提供しているServiceとサービス層のファイル名に使われるServiceが同じ英単語のため、コード上でServiceがどっちの意味かわかりにくい箇所ができてしまったと気づき、再検討となりました。
そして次に候補に挙がったProducts
よい単語だと思ったのですが、これも開発でよく使われる本番環境=Productと被ってしまうと指摘を受け再検討となりました。
最終的にContentsという単語を採用しました。
学んだこと
- 予約語(開発でよく使われる単語)と被らないことが重要！
- テーブル名からどんなデータが入っているか予測できることが重要！
テーブル名１つにしても名前を決めることは大変です。
命名する時にどんな基準で考えるか(学んだこと２点)のポイントをまとめておくと良いです！チーム内でいろんな候補が出てきましたが、基準を設けることで、迷わない対策が取れました。
APIのURL設計をしてみて
「指定したコンテンツID(contentId)に紐づくタグ一覧を、グループ付けした状態で表示させる」機能のプルリクエストを出したところ、下記のような指摘をもらいました。
http://localhost:8080/tag/list
→タグがリストを持っているわけではなく、タグのリストですよね？
http://localhost:8080/tags/1
→/tags/{tagId}を連想してしまいますよね！？
contentIdで検索するという意図が見えないですよね！？
http://localhost:8080/tags?contentId=1
→グループ付けした状態で表示させたいので、tagsではなく、tag-groupsですよね！？
最終的にhttp://localhost:8080/tag-groups?contentId=1を採用しました。
学んだこと
-
どのようなリソースを扱うかが明確にわかるURLがよい！ - 誤解されない名前にする！
何の情報を扱うAPIなのか見てすぐわかる名前にしておくことで混乱も起こらない。同じような機能で書き方が異なるのも避けたいので、API命名規則を決めて運用することになりました。
O'reillyのリーダブルコードを読んでみて
「プログラミング初心者は読んでおいた方がいい」とおすすめされ、お問い合わせツールの開発を進める合間に読んでいました。
古い本ですが「とても役に立つ」や「この本を読んでおけば、あんなにプルリクエストで指摘を受けて凹むことなかったかも」など社内でも評判のいい本です。この本の中でクラス名やメソッド名を考える時のアドバイスが書かれていました。印象的だったのが、
- 名前に情報を埋め込む
- 誤解されない名前にする
- 明確な単語を選ぶ
- 具体的な名前を使って、物事を詳細に説明する
例えば、よく使いそうなgetやstopについて書かれていました。
getとは、どこからとってくるのかが明確でない！
Stopも動作に合わせて、Kill,Resume,Pauseなど使い分けてもよい
など。
学んだこと
- 象徴的な単語よりも、より具体的な単語を選択する
- 英単語には同じような意味を持つものが存在するので、ケースに応じてより具体的な単語を選択する
初めてコードを見る人に対して明確になっていることが大切！理解するために時間がかかってしまうとかなりのタイムロスになることを学びました。
なぜ適切な命名がこんなに大切なのか？
私は今までバリバリコードを書く開発をしてこなかったので、正直、命名がこれだけ大切だとは思っていませんでした。
最善の名前とは、誤解されない名前である。
つまり、君のコードを読んでいる人が、君の意図を正しく理解できるということだ。
リーダブルコードに書いていました。
自分が理解していればそれでいいではなく、初めてテーブル設計やコードを見る人に対して明確になっていることが大切！誤解されやすい名前や曖昧な単語が使われていたら、理解に時間を費やしてしまいタイムロスになります。また、バグを生まないようにできるメリットも大事なので、品質の高いソフトウェアを作るためにも、わかりやすい命名は欠かせません！
より早く正確に実装を進めるためにも、命名がいかに大切かを学びました。
最後まで読んでくださり、ありがとうございました。
それではみなさま、HAPPY MERRY X'MAS!!!