詳細設計で先輩エンジニアからアドバイスされたこと

概要

先輩エンジニアに詳細設計をレビューしていただいた際、多くの指摘やアドバイスを受けました。
その内容を整理し、具体的な改善とともに、記事にまとめました。

対象読者

• 詳細設計のポイントを確認したい人
• 1〜2年目のエンジニア

1. 構成を統一する

設計書の構成を統一することで、可読性が向上します。
また、Notionなどのツールを活用してテンプレート化するのもおすすめです。

例：

# 概要
# 設計
## DB
## ルーティング
## 処理内容
1. 処理内容1
    - 処理内容1-1
        - 処理内容1-1-1
    - 処理内容1-2
2. 処理内容2
    - 処理内容2-1
    - 処理内容2-2

2. 前提を記載する

設計の背景や理由が明確でないと、レビュアーもフィードバックしづらくなります。
前提を記載することで、レビュアーもスムーズに内容を理解することができます。

例：

〇〇が原因で、〇〇ができない不具合が発生しているため、〇〇を修正する。

3. 図で表現する

複雑な処理やテーブル定義は、テキストだけでは理解しにくいことがあります。
図を活用することで、伝わりやすい構成にすることができます。

例：ER図（テーブル定義）

例：フローチャート（処理の流れ）

4. 書き終わったらチェックする

詳細設計を書き終えた後に見直すことで、ミスや抜け漏れを防ぐことができます。
特に以下のポイントを確認しましょう。

• 一貫性があるか
  • 用語
  • フォーマット
• 伝わりやすい文章になっているか
  • 文章が長くなりすぎていないか
  • 意図が理解できるか
• 不要な情報が含まれていないか
• 参照先のURLが誤っていないか

まとめ

先輩エンジニアからのアドバイスを受けて、読み手にとって「分かりやすく」「伝わりやすい」設計書を書くことが重要だと学びました。
図の活用や構成の工夫、前提などを意識することで、より良い設計書を作成できるようになります。

設計の品質を向上させるために、ぜひこれらのポイントを意識してみてください！