WebとかIoTのブログ

複数人での開発する上で、タブやブラケットなどのコーディングポリシーが曖昧だと、Pull Requestなどで差分をチェックする際に余計な差分が出てしまったり、それにより一貫性のないコードが増えていくという悪循環が生まれてしまうといった問題が発生してしまいます。

最近WordPressのオリジナルテーマを制作する案件で複数人での開発を行う機会を得たため、どのようなガバナンスの方法があるのかを話し合ってみることにしました。その内容を記事化します。

コード整備の方法

コードベースの一貫性を保つための仕組みを作成する方法として、一般的に次のような方法が挙げられます。

なお、上に位置するものはシステム化の度合いが高い方法であるという並び順になっています。

• Formatterの利用
  • 例：Prettier
• Linterの利用
  • 例：ESLint, JSLint, PyLint
• 静的コード解析ツールの利用
  • 例：SonarQube
• CI/CDツールの利用
  • 例：PR作成時に規定のルールに沿っているかチェックしてfeedbackする
• コードレビュー
  • GitHub、GitLab、Bitbucket
• ペアプログラミング
• ドキュメンテーション
  • 例：コーディングルールの策定

どれを使うべきなのか

色々な方法がある中で、どういう観点でどれを選択するのがよいのでしょうか。いくつかの問いや注目すべきポイントを挙げてみます。

• あなたのチームで重要なことは何でしょうか
  • Quality
  • Cost
  • Delivery
• 例えば、今回の我々のチームに当てはめると、予算は潤沢とまでは言えず、スピード感ある対応が求められます。となると、Costがかけられず、Deliveryを優先せざるを得ないならQualityは最小限というバランスを取るべきでしょう。なお、これは悪いことではないと筆者は考えます。「最小限」だけチームで定めましょう。
  • 空白とかのポリシーだけ定めて、あとはプルリクで解決とか、カットオーバー（納品・公開）できてから振り返るのでも全然いいのではないか？
    • 空白だけでも定めたほうがよいと思った理由は、差分が分かりづらくなること

気になること

どの方法を取るべきかの合意が取れたところで、一旦立ち止まって考えるべきことがあります。それは本当に実現性があるのでしょうか？

• FormatterやLinterは各メンバーのエディタ設定に依存するため、本来守るべき規約に沿っていないコードがコミットされうることの回避は難しい
  • CI/CDツールでLinterを利用してエラーを検出する、というのは良さそう
• Formatterが期待動作しないことで全体の進捗が犠牲になる場合がある
  • コードで管理することで防げるのでは？

WordPressにおける開発で注意すべき点は次の通り

大まかな方法が固まってきたところで、WordPressにフォーカスしたやり方を考えていきました。結論、WordPressのコーディング規約をベースにし、その上で納品先のコーディングルールに合わせてアジャストするべきでしょう。

• 納品先のコーディングルール
• WordPressの標準コーディングルール（CSS/HTML/JavaScript/PHP）
  • WordPress コーディング規約 – Japanese Team https://ja.wordpress.org/team/handbook/coding-standards/wordpress-coding-standards/

コーディングルール作成観点

WordPressにフォーカスするという合意は得られた上で、それでもチームでやりたいスタイルを追求すべきでしょう。というのも、別にWordPressコアのコードベースにコミットするわけではないのですから、チームがやりたい方法を多少取り入れても問題はないばかりか、モチベーションの維持に良い作用が期待できるでしょう。

今回はこのような点について話し合ってみました。

1. インデントスタイル：タブを使うか、スペースを使うか。また、何文字分のスペースをインデントに使用するか。
2. 命名規則：変数、関数、クラスなどの命名についてのルール。キャメルケース、スネークケースなど。
3. コードの長さ：一行の文字数や、一つの関数・メソッドあたりの行数、クラスあたりのメソッド数など。
4. コメント：コメントの書き方、また必要な場合と必要でない場合の区別。
5. コードの構造：クラスや関数の設計、モジュールの分割、パッケージ構造など。
6. エラーハンドリング：例外をどのように扱い、どのように報告するか。
7. テスト：単体テストや統合テストの範囲と方法。
8. ドキュメンテーション：関数やクラスの説明をどの程度詳しく書くか。
9. 使用言語の特性：特定の言語の特性をどの程度使用するか。たとえば、Pythonのリスト内包表記やJavaScriptの三項演算子など。
10. ユニットテストと統合テストの範囲：どの部分に対してユニットテストを書くべきか、どの部分に対して統合テストを書くべきか。
11. コードの再利用：コードを再利用するための最低限の要件。
12. データ構造とアルゴリズムの選択：特定の状況下でのデータ構造とアルゴリズムの選択。
13. ソースコードのレイアウト：ブレース（{}）の位置、空行の使用など。

ちなみに、我々のチームでは、意外と、タブじゃなくて空白スペースにしたい・・という意見が強くて驚きでした。これは一番意見が分かれたところです。

おすすめ

さて、色々とここまでで目線合わせがかなり進みました。

最後に、ディスカッションの中で興味深い話が出ましたのでリストアップしておきます。読者の参考になれば幸いです。

• CIでLinterを走らせる方法がある
  • actionsで、pushされた時に、npm commandsとかで、linterを実行する
• 言語ごとにコーディング規約、ツールの導入難易度が異なる
  • Goとかは容易、PHPは難あり
  • コーディング規約自体のゆらぎ
• WordPressのコーディングルールについて
  • 日本人向けには少し合わない部分もある
  • 非常に多くの人が関わる
• PHP Standards Recommendations – PHP-FIG https://www.php-fig.org/psr/
  • FIGというワーキンググループに参加している団体で認識合わせするためのものなので、PHPユーザ全体をメインターゲットにしている訳では無い
• WordPress公式テーマの利用
• WordPressの案件には是非コーディング規約を導入してください！ – Qiita https://qiita.com/yousan/items/35e64ba6492e9c459c12#composerでのphpcswpcsphp-compatibilityのインストール
• Airbnbのコーディング規約、理由とか実例が充実しててよい
  • Airbnb JavaScript スタイルガイド() { | javascript-style-guide https://mitsuruog.github.io/javascript-style-guide/
• コメントを書きましょう
• 名書「Readable Code」読みましょう