皆どのようにしてコードを書いてるのか？ - フォトシンスエンジニアブログ

この記事は Akerunのカレンダー | Advent Calendar 2022 - Qiita の 24日目の記事です。こんにちは Esperna - Qiitaです。ファームウェアの開発を担当してますが、最近nodeJSとGoを触ることが多いです。

背景
内容
- 成果物フォーマットの一例
所感
参考文献

背景

コードを書くときって皆どんなプロセスで書いてるのか気になりませんか。自分は気になってます。個人的にはこれまで複合機、電子黒板、車載カメラ、SSD、スマートロック等の組み込みソフト寄りの開発をしてきましたが、製品、業界、開発のフェーズ（研究・要素開発よりから製品開発、運用・保守までのどこか）等によって、ソフトウェアのコンストラクション*1の仕方が異なります。そこで、まずは改めて自分がどのようにしてソースコードを書いているのか整理してみました。

内容

仕様と既存の設計（というかソースコード）を読んで、要求を整理した後、（可能であれば）クラス図を書いて、どのクラスに何をさせるか整理します。その後、ソースコードを書くより前に単体テストを書いてソースコードを書いてます。ソースコードを書くまでに下記の設計の成果物までは書きたい派です。実際に書くかどうかは開発期間、プロジェクトの状況、会社の文化だったりその時々によります。以下はソースコードを書いていく過程でアウトプットとして意識する成果物のフォーマットの一例です。

成果物フォーマットの一例

背景

目的

スコープ（どの機種・プロジェクトに適用されるのか）

要求分析

やることリスト
ユースケース図

テスト設計

テスト仕様書

分析

クラス図（責務分担）

設計

設計指針
クラス図
シーケンス図
状態遷移図

実装

ソースコード
静的解析結果

テスト

テスト結果報告書

下記は上記の成果物に対して私が思うところです。

	成果物	内容	何故必要か
要求分析	やることリスト	プログラミングをすることで実現する振る舞いのリストを書く。	ソフトウェアを書くことでどんな振る舞いを実現するのか明確にするため
	テスト仕様	主に実機テスト仕様を書く（なるべくテストファーストで(ソースコードを書く前に)書く）。可能なら他の人が見て同じ手順を実行できるレベルで書くのが理想。	評価の視点を明確にするため。評価項目に漏れがないことを確認するため。評価手順を明確にするため。
	ユースケース図(ユースケース記述)	システムに関わるステークホルダを明確にする。ユースケースに関わるシナリオを明確にする。	ユーザの使い方や運用を含めたシステム全体のシナリオを意識するため
分析	クラス図(責務分担)	各クラスの責務を整理する	特定のクラスに責務が集中してコードが複雑になったり、密結合になったり、ソースコードの可読性が下がるのを避けるため
設計	クラス図	データ構造やデータの有効範囲、スコープ、責務の整理を行う	ソースコードが複雑になったり、ソースコードの可読性が下がるのを避けるため
	状態遷移図	各状態に応じたイベントの有無、イベントに対する振る舞いを明確にする	状態に応じた複雑な振る舞いをバグらずに書くため
	シーケンス図	ソフトウェアの動的な振る舞いを記述する	各インスタンスの処理の流れを明確にするため
実装	ソースコード	関数やメソッドの詳細を実装する	ないとソフトウェアは動かないため
	静的解析結果	lintやQACを実施する	バグを回避するため。Warningが多いとより危険なWarningを見落とすことがあるため。
テスト	単体テスト報告書	単体テストのカバレッジレポート	どのパスがテストされていてどのパスがテストされていないかを明確にするため。カバレッジ（％）は参考値。
	結合テスト報告書	実機で動作確認した結果を書く。エビデンスのログを残す。	評価のエビデンスを残すため。テストチームへの参考資料として共有するため。

所感

こうして書いてみると全部やるのはなかなか大変ですね。でも、

自分たちが作っているのは製品ではなくサービスなので、ユーザシナリオや運用、セキュリティ含めてサービスやシステム全体のシナリオをもっと意識して要求分析の成果物を残しつつコードを書きたい
責務を明確にして設計が複雑にならないようにするためにクラス図を書くことを大事にしていきたい
コマンドを打ってクラスやメソッドの説明が出てくると調査に便利なのでGoDocのようなものを残していきたい

と思いました。他のエンジニアがどのようにしてコードを書いてるかぜひ知りたいです。