会社設立4年目にしてコーディングガイドを作った話
SIROKの片岡です。今日は、エンジニア向けにコーディングガイドを作った話を書きます。
コーディングガイドを作った経緯
SIROKの設立当時はエンジニア3人ほどでスタートしましたが、それから3年半で関わっているエンジニアのメンバーが20人近くになりました。
メンバーが増えて、今まではなんとなく空気で共有されていた「こう書くと良い」を、改めて明文化する必要が出てきました。
そこで先日、エンジニアメンバーのみんなに「プログラムを書く上でみんなが気をつけた方がよいと思うことはなんだろう？」と聞いたところ、「自分はこういうことを気をつけて書いているよ」というポイントががたくさん集まりました。
それを元に「SIROKコーディングガイド」を作りました。
みんなが色々意見を出してくれて実際には100項目くらいになっているのですが、その一部を紹介します。
コーディングガイドの前提
そもそもコーディングガイドを作ったのは、良いプロダクトをスピード感をもって生み出すために、お互いに読みやすい良いコードを書きましょう、という前提があります。
そこで、コーディングガイドはこういう前提の共有からはじめています。
- このガイドの最終目的は、良いプロダクトを素早く生み出すことです。
- そのために、「何が良いコードか？」について共通の認識をもち、みんなが良いコードを書けるようになりましょう。
- いまいちな規約はどんどん指摘して改善していきましょう。
ガイドを作る上で気をつけたこと
今までは、あえてこういうルールのようなものを作らないできました。なぜかというと、エンジニアはルールに縛られるのを嫌うこと、人によって一番パフォーマンスの出るやり方は違うためです。
そこで、今回コーディングガイドを作るにあたって、2つの点について気をつけました。
理由をセットにすること
理解不能なルールは受け入れられない人が多いと思うので、理由をセットでつけることにしました。反対に合理的な理由のない好みの問題は、できるだけルール化しないようにしました。
拘束力を弱めにすること
理由を理解した上で違うやり方の方が優れていると考える場合は、部分的にガイドから外れても良いというスタンスです。そのために、「コーディング規約」という名前ではなく「コーディングガイド」という名前にしました。
SIROKコーディングガイド(一部抜粋)
記法を統一し、混在させない
誰が書いても同じになるような状態にするため、言語ごとの慣習を踏襲する。言語によって、lowerCamelCase、UpperCamelCase、snake_caseを使い分けるが、lower_camelCaseみたいなのは避ける。
コメントには何をしているかではなく、何のためにしているのかを書く
コメントでソースコードが肥大化してかえって読みにくくなるのを避けるため、基本的にはコメントをつけなくても何をしているかが分かるようにコードを書く。何のためにしているかはコードでは伝わりにくいので、補足するためにコメントを書く。
コメントアウトで古いソースコードを残さない
コメントアウトされたコードがあると読みにくくなるが、残しておいても誰も保守しないため。Gitで履歴管理するようにして、コメントアウトでソースコードを残さない。
変数名を省略しない
たとえば、cntでなく、countと書く。誰が読んでも間違いなく同じ解釈ができるようにするため。書く人によって略し方が異なると読みにくくなるので、省略しない状態に統一することで誰が書いても同じになるようにする。
テーブル定義、データアクセス層、ビジネスロジック層、コントローラ層、API、ページURLの命名やデータ構造を揃える
最下層から、上位層まで、同一の名前やデータ構造を保つことで、混乱を避ける。
データ設計をする際、命名は1単語で可算名詞がオススメ
2単語以上だと、形容詞を加えたときにどこに区切りがあるのかわかりにくくなるので、1単語で表現できる場合はできるだけ1単語で表現する。可算名詞だと、リストオブジェクトの命名が複数形にするだけで機械的にできるため。
データベースに保存するデータは生の形にする
データベースにはできるだけ生のデータを保持し、エスケープなどはビューの階層でおこなう。エスケープ済みかどうか分からなくなって、エスケープし忘れたり、多重にエスケープしてしまわないようにするため。
自由度の低い状態を文字列で表現しない
文字列だと1文字のミスで不定状態になるため。たとえば、public/privateのような真偽情報はbooleanで、active/inactive/invalidなどのステータスなどはenumで表現する。
Gitのコミットメッセージはある程度具体的に
あとから見返した時に、なにを変更したか、なぜその変更をしたかが理解できるように書く。「変更した」みたいなのは避ける。
Gitは、git flowっぽく運用する
開発はfeatureブランチ。完成したらdevelopブランチにマージ。本番リリースは、masterブランチにてマージしておこなう。
コミットはこまかめにする
コミットが大きいと、何をやっているかわかりにくくなるため。また、あとでマージが大変になるため。
同じブランチで作業している他の人の作業に対して自分のコミットは、 git rebase で先端につける
マージコミットだらけでコミットログが読みにくくならないようにするため。
APIのレスポンスはJSON型
最近のWeb系エンジニアは、みんなJSONのレスポンスに慣れているため。
コンパイルチェックが効くように書く
コンパイルチェックで問題を早期検知できるようにするため。TypeScriptはJavaScriptのように型の制約なしに書けてしまうが、型を可能な限り利用する。
ソースコードは200行以内くらいにおさめる
経験則として、それを超えているとだいたい設計が怪しいため。
ネストは2階層くらいまでにする
if文で条件をみたさない場合はすぐにreturnし、後続の処理はifブロックに入れない
