概要
コードレビューでコーディングスタイルやルールの指摘は、繰り返し行われる機械的な作業です。この部分をツールに任せれば、コードレビューの時間を減らし、レビュアーが機能やロジックなどの本質的な問題に集中できるようになります。
現在、コードレビューでコーディングスタイルの指摘や修正にかなりの時間がかかっています。チーム内で合意されたコーディングルールの中で、ツールで自動検査できるものはツールに任せ、コードレビューを効率化する方法について紹介します。
コードスタイル統一のメリットとデメリット
コードレビューでコーディングスタイルをチェックしなければレビュー時間は減りますが、コードスタイルを統一することには多くのメリットがあります。コードスタイル統一のメリットとデメリットを見ていきましょう。
メリット
コードの可読性向上
開発者は新しいコードを書く時間よりも、既存のコードを読んで理解する時間の方がはるかに多いです。
- Robert C. Martin (“Clean Code”)：開発者は作業時間の10％だけを新しいコードの作成に使い、90％は既存コードの読解と理解に使う。
- Camille Fournier (Software Engineering at Scale)：開発者がコードを読む時間はコードを書く時間の3倍多い。
- IEEEとACMの研究結果：コードの可読性が改善されると、開発速度とメンテナンス効率が大幅に向上する。
コードスタイルが統一されると、既存コードを読んで理解する時間が減るため、全体的な開発生産性が向上します。
メンテナンス効率の向上
- コードの追加や修正時、既存コードを理解する時間が減ります。
- デバッグやリファクタリング時の混乱を減らし、効率的に作業できます。
協業効果の向上
- チームメンバー間でコードスタイルが統一されると、コードレビュー時間が減り、生産性が向上します。
- コードスタイルに関する議論の時間を減らし、機能や論理的な問題に集中できます。
オンボーディング時間の短縮
- 新しいメンバーがプロジェクトのコードベースを理解してコミットするまでの時間が減ります。
- 学習コストが減少します。
エラーの減少
- 統一されたコードスタイルで開発すると、作成時のミスが減り、バグを減らせます。
デメリット
初期導入コスト
- コードスタイルを統一するためにスタイルガイドを作成したり、既存コードをリファクタリングする必要があります。
- LinterやFormatterのツールを設定して適用する時間がかかり、この期間は生産性が多少低下する可能性があります。
ルール合意に時間がかかる
- どのスタイルを採用するかを決めるのに時間がかかります。
- すべてのメンバーが満足するスタイルを見つけるのが難しく、議論が長くなることがあります。
創造性と柔軟性の制限
- 厳しいスタイルガイドがあると、個人的なコーディングスタイルが制限されます。
- 開発者が自分なりの効率的な方法を試すのが難しくなることがあります。
既存コードとの互換性の問題
- すでに作成されたコードが多い場合、新しいスタイルガイドと不一致して、コードベースに2つのスタイルが共存する可能性があります。
- 既存コードの修正に追加の時間が必要です。
Linter/Formatterのオーバーヘッド
- LinterやFormatterでエラーが複数回発生して、修正に時間がかかることがあります。
- LinterやFormatterの実行時間が追加されます。
コードレビュー自動化ツール
コードレビューでコーディングスタイルやルールをLinterなどのツールで検査することで、コードレビューの自動化を実現できます。以下は代表的なツールです。
- ESLint: JavaScript/TypeScriptコードの文法とスタイルの検査ツール
- 公式ドキュメント: https://eslint.org/
- Stylelint: CSS/SCSSなどスタイルシートコードの文法とスタイルの検査ツール
- Semgrep: 正規表現ベースのカスタムルールでコード検査が可能な静的解析ツール
参考として、Googleもスタイルガイドドキュメントとツールを運用しています。
ESLintとStylelintのルール追加
Linterで検査できるコーディングルールがあれば、Linterのルールを追加して自動で検査できるようにするのが良いです。Linterのルールを追加する方法については、以下のブログ記事を参考にしてください。
ESLintルール追加の例：
Stylelintルール追加の例：
Semgrepとは
Semgrepはコードのセキュリティ、品質、スタイルを自動で検査して改善するための静的解析ツールです。主にソースコードを分析してセキュリティ脆弱性、バグ、コード品質の問題を見つけるために使われています。
Semgrepはユーザー定義のルールを正規表現で作成することができ、Linterでは検査が難しい部分も検査できます。
例えば、コメントで説明を書かなかった-がある場合、Linterでは検査できませんが、Semgrepを使えば検査できます。
間違った例：
/**
* Add two numbers
* @param {number} a - number for addition
* @param {number} b -
* @returns {number}
*/Semgrepのインストールと使用方法については、以下のブログ記事を参考にしてください。
コーディングルール追加プロセス
コードレビュー自動化を効果的に運用するためには、コーディングルールを追加するプロセスを確立することが重要です。以下はコーディングルール追加プロセスです。
1. コーディングルールの検討
コードレビュー時にコーディングスタイルの統一やルール化したいものがある場合、チケットを作成してチーム内で共有し、ルール化するか検討します。
2. コーディングルールに追加
決まったルールをコーディングルールドキュメントに記載します。
3. Linterルール追加の確認
ルール化することになったら、まずLinter（ESLint、Stylelintなど）で検知できるか確認します。検知できる場合、そのルールを追加します。
Linterをgitコミット時に自動で実行するには、Git Hooksツールを活用できます。
4. Semgrepルール追加の確認
Linterルールで検知できないコーディングルールの中で、正規表現で検知できるものはSemgrepルールを追加します。
5. コーディングルールにリンクを追加
コーディングルールドキュメントに自動検査ツールのルールリンクを追加しておきます。自動で検知できるものはドキュメントに記載しなくても良いかもしれませんが、Googleのスタイルガイドのようにドキュメントとして残すのも良い方法です。
Semgrep活用例
以下は、Semgrepを活用してコメントで説明が抜けているパラメータを検査するルールの例です。
rules:
- id: missing-param-description
severity: ERROR
message: 【コメントエラー】正しいコメントを追加するか、コメントの`-`文字を消してください。
languages:
- javascript
- typescript
patterns:
- pattern-regex: \*\s*@.*-\s*(\n|\r\n|$)このルールは以下のようなケースを検査します。
間違った例：
コメントで-の後に説明が書かれていない場合、エラーが発生します。
/**
* Add two numbers
* @param {number} a - number for addition
* @param {number} b -
* @returns {number}
*/正しい例：
すべてのコメントが正しく書かれている場合、エラーは発生しません。
/**
* Add two numbers
* @param {number} a - number for addition
* @param {number} b - number for addition
* @returns {number}
*/完了
このブログ記事では、コードレビューで機械的にチェックできるコーディングスタイルやルールをツールで自動化し、コードレビュー時間を減らす方法について紹介しました。
コードスタイルの統一には初期導入コストやルール合意に時間がかかるデメリットがありますが、長期的にはコードの可読性向上、メンテナンス効率の向上、協業効果の向上など、多くのメリットがあります。
ESLint、StylelintのようなLinterとSemgrepを活用すれば、コードレビューで繰り返し指摘されるコーディングスタイルの問題を自動で検査できます。コーディングルール追加プロセスを確立し、Linterで検査できるものはLinterに、Linterで検査できないものはSemgrepに任せるのが効果的です。
コードレビューで繰り返しスタイルの指摘に時間を費やしているなら、ツールを活用した自動化を検討してみてください。
ESLintルールを追加した具体的な例については、以下のブログ記事を参考にしてください。
私のブログが役に立ちましたか？下にコメントを残してください。それは私にとって大きな大きな力になります！
アプリ広報
Dekuが開発したアプリを使ってみてください。Dekuが開発したアプリはFlutterで開発されています。興味がある方はアプリをダウンロードしてアプリを使ってくれると本当に助かります。
