コードの品質を測定し、保証するための基準とは？

はじめに

私のキャリアの中で、初心者の開発者と経験豊富な開発者がコードの書き方や品質に対してどのようにアプローチするかに大きな違いがあることに気付きました。初心者は特定の目的に集中しますが、経験豊富な開発者は、さまざまなパラメータを考慮したより広いアプローチを取ります。

この記事では、グローバルなアプローチを採用し、測定可能な基準を使用して、どのように開発の品質を向上させるかを説明します。

グローバルアプローチ

キャリアの初期段階では、最も重要なのは主要な結果を得ることができるコードを作成することです。これは論理的ですが、実際には、期待される結果を得ることは思ったほど重要ではありません。むしろそれは二次的なものです…

実際、コードの最初のバージョンがうまく動作しないことは非常に一般的です。最終的にはコードを機能させる必要がありますが、それは修正するのが最も難しい部分ではありません。

一方で、コードの最初の試行に構造的な問題があり、変数名やメソッド名が不明瞭で、ベストプラクティスに従っていない場合、後々問題が発生する可能性が非常に高くなります。

だからこそ、経験豊富な開発者は、仕様のいくつかの詳細を確認し、確認し、再検討することに多くの努力を費やします。仕様がニーズに最も効果的に応える方法に沿って記述されているかどうかを確認します。その後、さまざまな技術的アプローチを模索し、最も適切なものを選択し、コードのアーキテクチャ、概念の命名規則、さまざまなユースケース、ソリューションがアプリケーションの他の部分に与える影響、エラーハンドリングのケースなどについて考えます。このリストは決して網羅的ではありません…

これらの側面についての思索が終わった後に初めて、純粋に機能的な側面に集中することになります。

このアプローチの利点は、長期的にメンテナンスがしやすいコードを生産することです。この利点には代償もあります。開発に必要な努力と時間は長くなります。これは短期的には不利ですが、すべての側面を考慮することで、バグのリスクを減らすことができ、明確で適切な命名規則を持つよく構造化されたコードは、コードの読みやすさを向上させ、適切な抽象レベルの使用は機能追加や変更を容易にします。

言い換えれば、コードに一気に取り掛かるほうが速いですが、このアプローチは後にバグ、パフォーマンスの問題、アプリケーションの進化の難しさという形で支払われることになります。

では、コードがメンテナンスしやすいかどうかを決定する要因は何でしょうか？

仕様書の段階

再び、仕様書の段階に注目しましょう。これらのドキュメントはしばしば軽視され、開発の中で時間がかかる割に価値が少ないと見なされがちです。

しかし、良く書かれた仕様書は次のことを防ぐことができます：

• 納品が不適合であること。 例えば、あいまいな表現が原因で、開発者が仕様書を作成者の意図通りに解釈できなかった場合があります。または、ドキュメントが長く複雑すぎて、開発者が一部の詳細を見落とすこともあります。
• 納品が適合しているが、実際のニーズに合わないこと。 例えば、インターフェースの選定ミスが考えられます。
• 設計やパフォーマンスの技術的問題。 たとえ機能的な仕様書であっても、将来のニーズを予測していなかった場合、アーキテクチャの選択が後々問題を引き起こす可能性があります。

仕様書を上手に書くためには、もちろん十分な経験が役立ちますが、しばしばそれだけでは不十分です。ドキュメントは、発注者と技術チームの両方でレビューされ、議論されるべきです。これらの議論がきちんと行われると、開発の品質に大きな影響を与えることになります。

私の経験では、常に同じ傾向を見てきました。最初は仕様書が軽視され、バグや矛盾（ある変更が別の機能やユースケースを壊す場合）で苦しんでいるうちに、仕様書の質を向上させるための努力（プロダクトオーナーの採用、レビュープロセスの追加など）が行われます。そして、必ず改善が見られますが、それでもすべての問題を解決するには至りません。

仕様書作成のアドバイス

良い仕様書を作成するために、私の方法は時間とともに大きく進化しました。普遍的な方法はありません。ある人はこの方法を面倒だと感じ、他の人は不十分だと感じるでしょう。それは、あなたがどれだけのコストをかける準備ができているか、または視点に応じて受け入れられる影響によって異なります。私が主に使用する形式は、ユーザーストーリーとバグ報告の2つです。ほとんどのタスクは、この2つの形式のいずれかで記述できます。

ユーザーストーリー

まず、タイトルは明確で以下の要素をきちんと記述する必要があります：

• アクター： アクターは開発の主な受益者です。
• アクション： 開発の主要な目的です。
• 目標/利益： アクションの実行によって得られる結果です。これは、アクターがアクションから得る利益に対応する場合があります。しばしば軽視されがちですが、開発の有用性を確認するために非常に重要です。目標が難しい場合、それは機能が実際には有用でない可能性があることを示しているかもしれません。

私が使うテンプレートは次の通りです： **<アクター>** として、私は **<アクション>** をしたい、**<目標>** のために。

例：顧客 として、私は 自分の注文リストを確認したい 、購入履歴を知り、サポートセンターの負担を軽減するため。

次に、私は執筆を3つのセクションに分けます：

• コンテキスト： 仕様書の目的を明確にするいくつかの文。執筆する際には、現在の状況と解決すべき問題を説明することができます。 前述の例を使うと：サポートセンターには、顧客が注文履歴を知りたいという多くのリクエストがありますが、この機能はアプリケーションに存在しません。
• 説明： これは、期待される結果をできるだけ正確に記述する部分です。プロジェクトや開発者の経験に応じて、このセクションには実装の詳細も含まれる場合がありますが、私は個人的には、技術的な詳細についてはできるだけ開発者に自由度を持たせるようにしています。
• 受け入れ基準： このセクションは非常に重要です。時には、説明の再定義になります。これにより、開発者は仕様書を正しく理解したかどうかを確認し、品質管理チームが納品時に拒否を避けるための基準を持つことができます。また、品質管理チームは、機能を検証するための作業基盤を持つことができます。

すべてのタスクに関して、これらのセクションに加えて、優先度を設定します。

バグ報告

良いバグ報告は、問題の修正を遅らせる誤解を避けるのに役立ちます。

タイトルは、問題を簡潔かつ正確に説明する必要があります。

例えば：メインページで、Enterキーを押しても検索が開始されません。

執筆時には、フラストレーションのあまり「リグレッション」という言葉を使いたくなるかもしれません。しかし、この言葉は報告書に明確に記録する場合を除き、避けるべきです（例えば、2つの異なるバージョンのアプリケーションで同じテストを行った場合など）。実際、多くの場合、この表現は不正確であるか、微妙にニュアンスが必要で、開発チームに「また壊しましたね」と伝えるネガティブなメッセージを送ってしまいます。これにより、職場の雰囲気が不必要に悪化します。

私のアドバイスは：実際にリグレッションがある場合でも、タイトルにその言葉を使うのは避け、本文で詳細を追加する方が良いです。代わりに、チケットに優先度を設定することができます。

報告書の本文は次の3つの部分で構成されます：

• 再現手順： 問題を再現するための非常に詳細な手順。
• 期待される結果
• 観察された結果

開発段階

開発段階では、以下のアドバイスを参考にして、開発の品質を向上させてください：

• 先ほども述べたように、グローバルなアプローチを取ってください。機能のすべての側面を考慮し、目的だけに集中しないようにしてください。その他の機能への影響、将来の進化、可読性、メンテナンス性なども考慮してください。
• コードの構造について十分に考える時間を取ってください。単純化が必要か、逆に追加の抽象レベルを加えるべきかを自問してください。
• できる限りベストプラクティスを適用してください。特に、KISS（Keep It Simple and Stupid - コードはシンプルに保つ）、YAGNI（You Are not Gonna Need It - 必要ないことはしない）、SRP（Single Responsibility Principle - 単一責任の原則）、DRY（Do not Repeat Yourself - 繰り返しを避ける）、車輪を再発明しない（車輪について学びたければ）など。
• パフォーマンスや最適化の面を考慮してください。SQLクエリは効率的ですか？ アルゴリズム的な問題はありませんか？
• ドキュメントについても考慮してください。常に必要というわけではありませんが、必要なときには書かなければなりません。存在する場合は、最新の状態に保つ必要があります。
• リンターを使用して、コードベースを均一にし、構造的な問題（複雑すぎるコードや良いプラクティスを守らないなど）を防ぎます。個人的には、Rubocopのすべてのデフォルトルールを使い、erb-lintのオプションルールのほとんどを有効にしています。
• 自動化されたテストを追加し、バグ修正のためには非リグレッションテストを作成してください。

開発の品質を測定する指標

これで、仕様書や開発の改善方法について私のアドバイスを知っていただきました。しかし、私にとってうまくいったことが、あなたにも効果的であるとは限りません。幸いなことに、これらを盲目的に適用する必要はありません。今からは、あなたの環境で品質の進捗を測るために使用する基準について見ていきます。

これらのアドバイスの導入には一定の努力が必要です。プロセス変更による進化と、チームのスキル向上やその他のプロセスの進化などの要因を区別することは難しいでしょう。いくつかの指標を追跡することで、最も効果的な手法を正確に特定することはできませんが、進捗を評価し、その結果に基づいて意思決定を調整するのに役立ちます。

以下は、あなたの開発品質を測るために追跡できる指標です：

• アプリケーション内のエラーの数
• 単位時間あたりに納品されたタスクの数（スクラムのポイントは直接使用しないでください。タスク数の方が信頼性が高く、副作用もありません）。
• スクラムのポイントの分布（与えられたポイント数のタスクの割合）。この指標は前述の指標を補完します（納品されたタスク数が増加しているが、チームがテーマをより細かく分けている場合、それは必ずしも生産性の向上を意味するわけではありません）。
• レビュー段階でのコードの見直し回数
• QA段階でのコードの見直し回数
• 更新されていない依存関係の数
• アプリケーション内の依存関係の総数
• 単位時間あたりのバグチケットの数
• 単位時間あたりの緊急チケットの数
• 単位時間あたりの技術的なタスク（コードのリファクタリングなど）の数。依存関係の更新などのメンテナンスタスクは除外します。
• これらのチケットの全体の負荷に対する割合、特にビジネス側からのチケットに対して
• 仕様書の段階にあるチケット（または/およびスクラムポイント）の数
• 開発待機中のチケット（または/およびスクラムポイント）の数
• 開発中のチケット（または/およびスクラムポイント）の数
• 自動化テストによるコードのカバレッジ
• アプリケーションコードに対するテストコードの比率

個人的には、これらの指標を現在自動的に追跡しているわけではありませんが、主観的にその進行状況を把握し、意思決定時に考慮しています。また、特定の選択肢を正当化するためにも使用しています。

これらの指標は、コードの品質が良いか悪いかを直接示すものではありませんが、その進化を追跡することで、品質が向上しているのか、低下しているのかを簡単に把握することができます。

結論

良い開発品質は単に機能するコードを作成することにとどまらず、仕様の明確さ、コード構造、保守性、そして将来的な変更の予測を含む包括的なアプローチに基づいています。このアプローチは初期投資が多くなりますが、誤りを減らし、長期的な生産性を向上させ、チーム内での協力を促進します。

厳密な仕様書の作成、慎重な開発、そして関連する指標の監視を組み合わせることで、プロジェクトの品質を段階的に向上させることができます。目標は絶対的な完璧さを追求することではなく（それは幻想にすぎません）、継続的な調整を可能にする反復的で測定可能なアプローチを採用することです。最終的に、良い品質のコードは開発者だけでなく、ユーザーや企業全体にも利益をもたらします。