コーディング規約 for small team 2018

1人AdventのDay-17です。17っていうとFLCLプログレを思い出す数字だな〜

adventar.org

コーディング規約というものがあります。
私は、割と「社内(のサーバサイドというかPHPというか)のコーディング規約をちゃんと皆で定めていきたいよね」側にいます。
その中にありながら、昨今では私も含めIDE/PhpStormの導入が進み、PHPCSもいるし、Phan/PHPStanもいるし、「機械的にやれること」は増えてきております。

原則として「既にあるコード」や「コードを書いた人(とその気持)」は尊重すべきだよな〜という気持ちがありまして、そういう意味で「わざわざtrailing commaをつける」だけとか「空白行を挟む」だけのコミットはしたくない、と思います。もしくは「コメントを消すだけ」とか。
自分が飛ばすPR、もしくはレビュー依頼を受ける事になる変更において「極力、diff行数が少なくなる」ように個人的には目指したかったりはするので、ケツカンマを入れる(配列に新しく要素を追加しても「前の行にカンマがついた」diffを出さなくて済むから)とか、「段落ごとに空白業を挟む」みたいなのは気をつけるわけです。
が、 それはあくまで個人的な話だ
コレを「チームで利用するコーディング規約に入れるか」という話を、・・・まぁ合意が取れたら規約として採用してもいいんでしょうけど、何か議論するのが疲れるってレベルのものがある。*1

規約というのはあくまで「健全性」「気持ちよさ」「効率」を引き出すためのものであって、「ストレスを抱えさせる」ためのものであってはならないよな〜と考えるのです。


愚痴を吐いたので、ここから本題です。

(先程述べた通り)私は「規約整備していこうぜ!」側でして、新しくサーバーサイドのエンジニアが入って共同のチームで動くよ!と決まったタイミングで整備をしたり、その後にはgithub管理移行とかも仕掛けたりをしました。
そうした活動を通して、自分なりに「健全性を高めるためにこういうポイントを抑えておきたい」と感じた部分があります。
その辺りの話を、少し整理してみようかなというのが今回のエントリーです。

前提のような方針のようなもの

「整備し直した」ものはCakePHP3のプロジェクト用のものでして、その「第0章」みたいな文章を書いてあったのでそれをそのまま引用してみます。

### コーディング規約の役割

チーム内で、「誰が書いても」「誰がレビューしても」同じ様にコードが書けて、違和感を持たずにコードが読めて、迷いを少なくしながら開発を進められる状態を理想とします。
狭義のスタイルガイドにとどまらず、推奨されるイディオムやプラクティスやフレームワークのバージョンアップ等に伴い生じる「注意の必要な書き方」をも示すことで、日常の開発業務において従うべき新鮮なガイドラインが欠かせません。

これを踏まえて、本文書は以下の役割を果すべきものと定義します。

* CakePHP3の経験の浅い新規参加者が、「どういう風に書くか」を把握できる
* CakePHP3の経験者が、「こうやると書きやすい/読みやすい」を普及できる

このくらいでいいんでないかな〜という規約

OSSのフレームワークを利用している場合、そのフレームワークの採用している規約がある場合が多いと思います。
なので、スタイルに関しての「守らないといけないもの」は、ベースとして「フレームワークが言っていることをそのまま」で良い、くらいに思っています。

これによって、コミュニティが持っているアセットを活かしやすくなるというのも重要。拡張改変バリバリの「本来のそれとは相入れない」ようなものを制定したら茨の道に突入していきます。

その上で、やってもいいかなと思っているもの

基本的に、自分たちのために作っているプロダクトというのはOSSなフレームワークほど「汎用的である必要」がない、と思っています。
そのため、実装についてもより(自分たちのための)アグレッシブな方針を取れるものと思います。例えば、「言語バージョンを新しくしたら使える機能」などです。

これらについては、「フレームワークの本家にはなくても、快適さを向上させる見込みがある」と判断できる場合もあるのではないでしょうか。そういったものは、あっても良いと思います。

あった方がいいかなと思っているもの

逆に、自分たちで作った機構やライブラリについては「利用するように規約で縛る」事でコーディングのし易さを支援できる可能性がある、と考えています。そうしたものは、積極的に「使っていく」ことに決めても良いかと思います。
なぜなら、「自分たちが自分たちのために作ったもの」であれば、サービスドメインやチームメンバーのレベルに合わせて開発されたものであり、フィットするはずだからです。

例えば、私の場合はenumのような機構を作りました*2が、これは「使うべき」としました。オプショナルでなく「使えるときは使う」ことによって、この機構の保守改善を行っていく恩恵が、プロジェクト全体に浸透していく状況を生み出せるようになるからです。
何より「メンバーがそれぞれに同様の書き方を扱えるようになり、リーディングにも実装にも没頭しやすくなる」ことが規約を定める目的でもあるので、足並みを揃えられられたのは良い点でした。

あると良いかなと思っているもの

私の仕立てた「コーディング規約」では、規約やガイド・・の範疇を超えた「プラクティス」の賞も設けています。
「こう書くべき」というとかなり強い制約になると思うのですが、ここには「こう書くとCakePHPぽいよ」といったものを拡充させていっています。
実は(規約自体はフレームワーク本体が抱えているにもかかわらず)「社内規約」を管理したい、というモチベーションの1つはこの「プラクティスを管理してみたい」という部分にもありました。

例えば、「CakePHPのEntityに値を入れるときに、どういった場合にはpatchEntity()メソッドを利用して、どういった場合にset()を使うのか?」といった内容に触れています。

当然ながら、「全員が守るべき・意識するべき」という規約よりも、周知徹底すべきなのはどのレベルからだっけ・・・?というのがファジーになるので、メンテナンスを続けていくのは中々ハードルが高かったりします。それでも、「プルリクで何度も指摘される」ような話は、こういった仕掛けで担保できないかな?とも思うわけです。

いずれにせよ

「なぜなのか」を示していくことが重要なのでは、と感じています。
もちろん、規約の中には「スペース4つで示す」といった、理論立てて説明し/されて納得感を持ちながら扱う・・というのとはそぐわないものもあります。他方で、例えば(実際にCakePHP3が採用している例で)「privateメソッドには引数の型宣言を行わない」という話をするときに「型宣言を行った場合、それを解釈し実行するコストが必ずしも0ではない」から、スコープが限定されるときは「なるべく負荷がないようにしよう」という理屈があると、助かるだろうな!と思うわけです。更に、「根拠を示す」ことが「改定を望むときにpros/consを明確にしやすくなり、本質的な議論に進みやすくなる」という利点もあります。

理屈をしっかりと明示していくことで、「コーディング規約」が「押し付けられるもの」ではなく「民主的に取り組み、常にアップデートされていくべきもの」へと進化させ得ると考えています。

まとめ

規約は堅苦しかったりストレスになる危険性もないではないわけですが、「関わる人全員をハッピーにしようぜ」というモチベーションから生まれるものだと思います。
コミュニティに開かれたソフトウェアのコーディング規約と社内やチームに適用されるべき規約とでは、そもそも目的も異なるはずで。なので、「自分たちのチームには何が必要で、どういったものがあればコーディング時の憂いがなくなるか」という原点に立ち返りながら、「ぼくらのかんがえたさいきょうのこーでぃんぐきやく」を以てして、最高のコーディングライフを手に入れられたらハッピーなのではないでしょうか!

*1:prettierくらい強烈に書き換えてくれるものやgofmtとか、救いだな〜!と感じる

*2:https://speakerdeck.com/o0h/bye-bye-magic-number