プログラムの詳細を書くには何がいいでしょうか？

Question

PHPで開発しています。
開発者は私一人だけなので今まではエクセルなどに適当なメモを残しながら作業をしてきました。

開発が進み思いのほか規模が大きくなりプログラムの詳細を覚えていられなくなりました。
プログラムの詳細を後から見てわかるようにするにはどのようなドキュメントを作ればいいのでしょうか？

特に処理をクラスにわけて細かくした辺りから自分でもよくわからなくなっています。
クラス図というのを書いてみましたがクラスの関係はわかりますが流れが表現できません。

流れでいくとシーケンス図かなと思っています。

書き表したいのは、ある1つの機能を実行するための流れです。（機能ごとに図を書こうと思います）

処理をするためにどのクラスを使うのか？そのクラスは何を受け取って保持するのか？どのメソッドを実行するのか？別のクラスを使うのか？別のクラスのどのメソッドを使うか？

といった内容になります。

目的は後から機能を追加したり修正する際にどのクラスを修正したらいいのかを掴むためで、詳細としてはどのメソッドを実行しているかまでです。処理自体の詳細は必要ありません。

もしかしてこういう事は図ではなく詳細設計書などの仕様書に書くのかも知れませんし、プログラム内にコメントを残して分かりやすくするものかも知れません。

一人で開発しているので一般的にどうしているのかが知りたいです。

プログラムの質問でなくて申し訳ありません。
あまりドキュメントに時間を割けないので図で表せたらなと思います。

図で表すべきではない（向いていない）ならそう教えていただければ結構です。
ドンピシャでなくても○○図をベースに書いたらいいよ的な感じで教えて頂ければ自分で調べることもできます。

よろしくお願いします。

Answer 1

まずは、UMLのダイアグラムを一通りみて、要望にあうか確認してみてはどうでしょう。
雰囲気的には、コミュニケーション図がよさそうですが・・・

UMLじゃないものもありますが、参考になれば。

https://www.ogis-ri.co.jp/otc/swec/process/am-res/am/index.html

https://www.ogis-ri.co.jp/otc/swec/process/am-res/am/artifacts/index.html

Comments

[msx2]

ご回答ありがとうございます。
返信が遅くなり申し訳ありません。
アジャイルモデリングは参考になりそうです、確かにコミュニケーション図がイメージに近いですね。
少しずつ見ていきたいと思います。

Answer 2

質問を読むに用途としては自分用ですよね。
ソースコードのdocコメント拡充で十分だと思います。
それ以前にファイル名だけで何の機能なのかアタリが付くように、命名規約、コーディング規約に時間をかけると良いです。

図は描いてもフローチャートと画面遷移図くらい？
設計書とか○○図はお客さんとか他の人に見せる必要があるなら書くかな。

Comments

[msx2]

ご回答ありがとうございます。

命名規約やコーディング規約がしっかりできていて守られていれば名前をみれば機能などのアタリがつくということですよね。
本業の開発現場ではそれが当然であって開発者に求められるスキルだと思います。

私はそういったスキルが不足しているために今回の質問をしましたが、後からソースコードとコメントを見ればわかるようにしたいと思います。

状況が許せばどこかの現場にお金を払ってでも修行にいこうかと本気で考えている今日この頃です。。

Answer 3

どのようなシステムなのか分かりませんが、画面があるものなら画面遷移図だけで充分だと思います。
そのプログラムを実行するトリガーさえ分かれば、だいたい流れは把握できますよね。
webサイトだったらトリガーが画面なので、画面遷移図だけでokというわけです。
クラスが多くなったり継承が深くなった場合でも、IDE使っていれば追えないということはないはずです。
要は「ソースコードがすべて」なのですが、それでもいいようにコード規約を作り、きれいで分かりやすいコードを書く必要があります。
理想を言えば、画面遷移図見ただけでコントローラやモデル、ビュー、サービスなど各クラスを連想できるよう、分かりやすい名前を付けることです。

実際の現場でも設計書より成果物優先ですね。
「どうせ見ないからドキュメントなんていらない」というクライアントさえいます。
いわゆる分かっているクライアントなら、「phpcsでpsr2準拠にしてくれ」とか「phpmd通してくれ」などと具体的な指示を出す場合もあります。
最近はテストもテストケースのファイルだけでokな案件も増えてきました。
金融系の案件でない限り、ドキュメントに固執するクライアントはいません。

ご自身で作られたシステムなら大雑把な流れは把握してますよね？
だったら、いかに文書として残すかを考えるより、いかに分かりやすいコードを書くかに注力すべきではないでしょうか。

Comments

[msx2]

ご回答ありがとうございます。
返信が遅くなり申し訳ありません。

きっとこの回答があるべき姿なんだと思います。
プログラミングが独学のため行き当たりばったり（とにかく動くものをつくるため）でソースを書いているために後からクラス名やメソッド名を見ても何をやっているのかわからないんです。要するにスキル不足なのですが。。
それを補おうと図で表したいと考えた訳ですが、わかりやすい名前とコメントでわかるようにするスキルを磨いていくべきですね。

指導してくれるメンターや参考になるソースを目にする機会もないので泥臭いやり方でもいいのでどうにかメンテナンスできる状態に持っていければと思います。

少しずつでもきれいで分かりやすいコードが書けるように努力しようと思います。
とても参考になりました、アドバイスありがとうございました。