Engineering Insights
ソフトウェアエンジニアにとって重要なスキルは、エンジニアリングデザインドキュメント（EDD）とも呼ばれる技術設計ドキュメント（TDD）を書くことです。 この記事では、良い設計ドキュメントを書くためのアドバイスと、避けるべき間違いをいくつか紹介します。
1つの注意点として、チームによって技術設計の標準や慣例が異なります。 開発チームによって状況に応じて異なるニーズがあるため、設計プロセスに関する業界全体の標準はありませんし、ありえません。 これから述べることは、私自身の経験に基づいて考えられる1つの答えです。
まずは基本的なことから始めましょう。 技術設計文書とは何か、そして、設計プロセスにどのように適合するか。
技術設計文書は、与えられた技術的な問題に対する解決策を説明します。 TDD の主な機能は、チームのメンバーに行われる作業の技術的な詳細を伝えることです。 TDD を書くプロセスでは、自分の考えを整理し、設計のあらゆる側面を検討し、何も見逃していないことを確認する必要がある。 これらは通常、製品要件文書 (PRD) によって表されます。 PRDは、ユーザーまたは外部のエージェントの観点から、システムが何をする必要があるかを指定する。 製品要件は、システムが何を達成しなければならないか、しかし、どのようにそれを行うかという技術的要件に変換される。 このステップのアウトプットは技術要件文書（TRD）である。 これは、前のステップで概説された要件に対するソリューションの技術的な説明を含んでいる。 TDDはこのステップの出力である。
このプロセスは非常に変化に富んでおり、ここに挙げた一連のステップはケースバイケースで変化することになる。 たとえば、
- あまり複雑でない小さな機能では、ステップ 2 と 3 はしばしば 1 つのドキュメントにまとめられます。
- 機能が多数の未知数またはある程度の調査を含む場合、技術設計を確定する前に概念実証の実装を構築することが必要になることがあります。 PRD/TRD/TDDは、システム全体の設計に関わる場合もあれば、1つの機能だけに関わる場合もあります。 ほとんどの環境では、このプロセスは周期的であり、各設計/実装サイクルは前のサイクルの作業の上に構築されます。
TRD と TDD の間の境界線は、時に少し曖昧になることがあります。 たとえば、RESTful API を介して通信するサーバーを開発しているとします。 もし目標がすでに確立され文書化された API に準拠することであるなら、API 仕様は要件の一部であり、TRD で参照されるべきです。 一方、全く新しいAPIを開発することが目的なら、API仕様は設計の一部であり、TDDに記述されるべきものである。 (ただし、要件文書には、APIが何を達成しようとしているのかを明記する必要があります。)
TDDを書く
最近では、Google DocsやConfluenceなどの共同文書システムで技術文書を書くことが一般的ですが、これは絶対必要条件ではありません。 重要なのは、チームメンバーがドキュメントにコメントを付けたり、誤りや欠落を指摘したりできる方法があることです。
ほとんどの TDD は 1 ページから 10 ページの間にあります。 TDDの長さに上限はありませんが、非常に大きな文書は編集が難しく、読者が吸収しにくくなります。実装の個々のステップまたはフェーズを表す別々の文書に分割することを検討してください。 Inkscape のようなオフラインのツールを使用して SVG 図を生成することもできます。
ドキュメントは徹底されるべきです。理想的には、TDD 作成者以外の人が、書かれたとおりに設計を実装することが可能であるべきです。 たとえば、設計が API の実装を指定する場合、各 API エンドポイントは文書化されるべきです。 3668>
Avoid Common Writing Mistakes
おそらく、私が TDD で遭遇する最も一般的な間違いは、文脈の欠如でしょう。 つまり、著者は、できるだけ少ない言葉で、どのように問題を解決したかを書きましたが、問題が何であるか、なぜ解決する必要があるのか、その特定の解決策を選択した結果はどうなったか、といった情報は含まれていませんでした。 読者が知らないような用語を使う場合は、恐れずにその定義を付け加えましょう。
良い文法とスペルが役立つことは、ほとんど言うまでもありません。 また、言葉遊びや「かわいい」スペリングの誘惑を避けましょう。プログラマは言語で遊ぶのが好きな傾向がありますが、過度の軽薄さが誤解のためにチームの無駄な労力を費やすことになったケースを何度も見てきました。 時折ユーモアを交えたり、機能やシステムにカラフルで覚えやすい名前をつけたりすることは、人々の記憶に残りやすいので良いことだと思います。 マーク・トウェインがかつて書いたように、「正しい言葉を選びなさい、その二番煎じではない」のです。 ボキャブラリーの乏しいエンジニアは、異なるものに対して同じ一般用語を何度も使用する傾向があり、過負荷と混乱を招きます。 例えば、あるクラスを “DataManager “と名付けると、そのクラスが実際に何をするのかが曖昧になり、何もわかりません。同様に、”utils “という名前のパッケージやディレクトリには、事実上どんなものでも含まれる可能性があります。 より良い言葉を見つける必要がある場合は類語辞典を、より良い場合は WordNet などの専門的な同義語データベースを参照してください。
TDD テンプレート
TDD を書く場合、標準テンプレートで始めると便利なことがあります。 以下は、私が多くのプロジェクトで使用したテンプレートです。 このテンプレートは、必要に応じてカスタマイズする必要があることに注意してください。