皆さんこんにちは。

夏ですね。暑いですね！
開発の方も燃えてませんか？ フェスって無いですか？
色んなお祭りがありますが、帰れないお祭りはちょっと避けたいですよね 😆

という事で今回から何回かに分けて
「開発を進めていく上で気をつけるべき事項」について
エンジニアの私の独断と偏見に溢れた記事を書き連ねて行こうと思います。

まず今回は今後記事にしていこうと思う内容(予定)の目次と、
最初の記事として「ドキュメントとソースで異なる名前をつけない」を
書いていこうと思います。

それでは宜しくお願いします。

目次

  1. ドキュメントとソースで異なる名前をつけない
  2. 名前は省略しない
  3. 速度より可読性を重視する
  4. 同じコードを書かない (関数化)
  5. 役割を分担する (クラス化)
  6. 仕様による制約をコードで表現する (より良いインターフェース設計)
  7. 何でも出来る→これしか出来ない
  8. 例外処理をちゃんと書く
  9. ログ出力にも設計を
  10. リリース作業は簡単に
  11. 環境変数の勧め
  12. まとめ

第１回 ドキュメントとソースで異なる名前をつけない

最近社内の勉強会で、ある既存プロジェクトの仕様書を元に皆でDB設計をしようという会があり、その時にも感じたホットなテーマなので1回目はこの題材にしようと思います。

勉強会ではDB設計をした事がないエンジニアも含めて4チームに分かれてそれぞれが仕様書と概要説明からDBのER図を作成するという流れだったのですが、各チームの最終的なアウトプットは大体同じ構成になっていました。

しかしテーブルやカラムの名前については色々なバリエーションが登場しました。
過去に他人が書いたソースコードを引き継いだり、レビューを行った際にも感じていた事ですが、ある概念を表現する時に一貫したルール(または方針)があった方が良いなぁと思っていました。

例えばユーザーを表現するテーブル名が3チームはUser, users, userなどだったが、1チームはDeviceという新しい概念名を採用していました。
もちろんある観点から見るとその方がしっくり来るのですが、仕様書に登場していない名称というのはそれを単体で見た時にピンと来ないかも知れません。

こういった事はDB名やテーブル名、カラム名だけに留まらず、URLのパス、クラス名、関数名、変数名、連想配列のキーなど様々な所で発生します。

これを問題と捉えるか否かは人によって様々だと思いますが、私の独断と偏見に満ちた判断では問題だと感じています。

そしてこれを防ぐ為のルール、方針として良いと思うのがドキュメントに登場する名称と一致させる事だと思います。

今回の例で言えば、仕様書にユーザーという表記があるのであればUser、user、usersといった表記を適切に使うというのが良いと思います。

形式(単数形、複数形、キャメルケース等)の使い分けについても別途対象毎に方針を定めると良いと思います。