理想論はおいといて現場の実感を踏まえてお願いします。
以下私の思考。
そもそもドキュメントツールの違和感(JavaDoc/PHPDocumenter/PHPDoc)は
・プログラム言語のヘルプファイルのようなドキュメントがクラスと関数単位で出来る。
・フレームワークや汎用ツールやライブラリのヘルプに作成に使うならならよいが、個別案件のドキュメントとしては人を突き放しすぎ？
・個別案件では意図や経緯や連携の説明が重要で、汎用的に関数を説明すると逆にわかりづらい。
・動きを説明するより関数の説明書になり全体像を忘れる。
＞関数単位の動きはわかるが全体として何かわからない。
・スッキリ分割されたプログラム言語やフレームワークのプログラムと比べ
個別案件のプログラムは構成が絡み合っており、部分を強調しても理解しにくい。。
No.1
104
3
60pt
同感です。
私はソースコードに余分なコメントが入ることで肝心のソースコードの可読性が下がってしまうように思います。
あと、ドキュメントを記載することに思考が持って行かれることで思考の分断が起きるのも嫌です。
再利用性が少ないコードに関しては関数名やクラス名を自己説明的にすることで対応可能だと思っています。
1
1
2
2
194
188
ですよねぇ。再利用性が少ないものもいっぱいありますよね。
現場ではどうも「なんでもかんでも/タダだから/オープンソースだから」とツールを詰め込みがちで、ありゃーと思っています。