内部仕様

内部仕様書はロジックを書くものではない
仕事やってて色々悩んだりしているので反応。

プログラム言語で整然と書かれたロジックを、自然言語に翻訳して冗長な文章を書かせるというのはナンセンスです。二重化されるため、メンテナンスの手間は倍になります。そもそもちゃんと同期させるだけでも至難の業。

うん。そんなん書くんだったら、ソースコードそのまま貼り付けるのが手っ取り早い。でも、コードの内容を理解せずに処理の概要を理解したい人向けに説明する必要がある訳で(いちいち見ている時間がないから)、そんなことは出来ない。とりあえず僕は、その処理のメインとなる流れを図で描き出して、「この条件の時、この流れがこんな風におかしな具合になっていたので、今回はこのように流れを変更します。おｋ？」的な説明をしているんだけど、この方法もまだ問題あるよなー。

• 作成者が理解している範囲でしか流れの説明をすることが出来ないので、記述されていない部分に問題があった場合、見逃される可能性が高い。そもそも、全部書き出すだなんて無理だし。全部知りたかったら、それこそコード読めって話だ。
• 時間がかかる。コーディングをして、さらにその説明のための資料作って、ってどれだけ二度手間なんだ。同じ対象を相手してるのに。

コードから説明に必要な資料を自動生成できて、レビュー中も必要に応じて色んな観点からの資料もさくっと作れるようなツールってないかなあ。無いよなあ。