過去に作成した開発標準を軽くいじったり、社内のセキュリティガイドラインを作る機会がありました。
その時に心がけていて良かったと思うことをまとめました。
心がけ
すでに世の中に出ているものを参照する
Python で言えば PEP8 のような世に広く知られたガイドラインが存在します。
このようなドキュメントがあれば「開発標準はそれに準ずる」と明記します。
また Effective Python のような定番の書籍も開発標準として活用します。
ガイドラインや書籍の中でどうしても組織に合わないお作法がある場合は例外として明記します。
まとまったドキュメントとして存在しない場合は細かくなりすぎない範囲で追記します。
全社的な開発標準は詳細を決めずにプロジェクトごとの柔軟性を持たせる
全社的な開発標準はゆるく設けつつ、細かい部分はプロジェクトごとに定めることを明記します。
メリット
上記2点を実践することで次のメリットがあります。
ドキュメントを作成するコストが小さくなる
すでに外部のドキュメントに記載されているため自分で書く必要がありません。
もちろん開発標準として参照するにふさわしいドキュメントを知っておく必要があるので作成する人は大変ですが、書かなくていいというだけでも楽です。
ドキュメントのメンテナンスのコストが小さくなる
作成コストが小さくなるのと一部重複しますが、メンテナンスのコストも小さくできます。
開発標準は一度定めて終わりということはなく、時代の流れに合わせてメンテナンスし続ける必要があります。
その際に毎回細かく書いたり消したりをするとメンテナンスのコストがかさんでいきます。
基本的に外部ドキュメントを参照しつつ、ゆるく全社的な開発標準を設けることでメンテナンスコストを抑える事ができます。
開発標準を読むメンバーの知識水準が上がる
開発標準に PEP8 や Effective Python に準ずると記載することでそれらのドキュメントを隅々まで読むことを強制できます。
これは同時に知識をインプットするコストがかかるというデメリットにもなり得ますが、最低限担保したいものに留めることでコスパのよいインプットになります。
例えば Effective Python を開発標準に取り入れている場合、レビューしているときに「 Effective Python にこういう事が書いてあるので読み直してください」といった具合に知識を身につけることを要求できます。
必ずしも開発標準的なことばかりが書いてあるわけではなく、開発標準以外の知識面が充足できます。
また知識の前提が揃うため、相手の知識レベルに遠慮せずに会話できるようになる点もメリットです（一回読んだくらいだとたいてい知識が十分に身についていないため、実際のところ根気強く伝え続ける必要はありますが）。
新規メンバーが入ったときに開発標準をインプットする手間が省ける
Python をまともに書く人なら PEP8 くらい知っていますし、Effective Python も読んだことがあると思います。
そのようなメンバーであれば、開発標準は PEP8 と Effective Python （+α）ですと伝えたらすぐに開発標準に馴染むことができます。
会社独自の開発標準を作っている場合はすべて目を通して貰う必要があるため、新規メンバーの負担が大きくなってしまいます。
開発標準として信頼されやすくなる
小さい組織だと開発標準を個人が考える場面もあるかと思います。
そのような場面で参照するドキュメントもないただルールだけが示された「オレオレ開発標準」だと反感を買いやすくなります。
つまり「それってあなたの宗教ですよね？」みたいな反応が出る可能性が高くなります。
開発標準のような派閥が存在するものにおいてはこういう主張はわりと普通に見かけますし、別に主張の内容自体は悪いわけでもないのですが、あまりにこういった反応が多いと開発標準を作り直すのも手間ですしメンタルにもきます。要するにめんどくさいです。
世に広く知れ渡ったドキュメントであれば信頼してもらいやすいく、反感を買いにくくなります。
開発メンバーのスキルやプロジェクト固有の事情に最適化した開発標準を作れる
全社的な開発標準をゆるく作っていれば、プロジェクトのメンバーからさきほどのような反発を受けてもある程度寄り添うことも可能です。
またスキル面で大半のメンバーが使ったことのないライブラリが開発標準に含まれていたりすると辛いケースもあるので、どうしても強制したいものでなければ柔軟性をもたせたほうが良いように思います。
感想
自分が実践して良かったと思うことを言語化してみました。
しかし SQL のフォーマットなんかは世に絶対的な標準が無いために詳細に決める必要があって結構つらいです。SQL は変化があまりなく、（今まで観測した範囲では）一度定めておけばメンテナンスがほぼ不要なのはせめてもの救いです。
Terraform は Terraform を使用するためのベスト プラクティス と 公式ドキュメントのスタイルガイドに従ってね、と言うだけでかなりカバーできて楽なんですけどね。
新しいものと古いもので開発標準の書き方やメンテナンスの頻度は結構変わってくるのかと思いました。
今回はエンジニア目線で書いていますが、非エンジニア向けの全社的なツールの使い方などのガイドラインを作る際やちょっとした仕事のルールづくりにも役立ちます。
特に日本の伝統的な企業は「世界標準」のような響きに弱く、独自のやり方を提案されて困りそうなときに外部ドキュメントを使って説得するとすんなり通ったりします。実際そのような標準に従うことが最善のことも多いので、相手のためにも日頃から標準を活用すると良いと思います。
この記事がお役に立ちますと幸いです。