どうもこんばんわ。
安藤＠るるねっとです。
2001/10/10 15:46:02 +0900にhamai@....jpさんに頂いた
「[XP-jp:02593] Re: 俺式 XP」への返事です。
>濱井です。
>2001/10/09 23:35:31 +0900にbugbear@....nuさんが送られた
>メールに関する返信です。
＜中略＞
>>ところで、XP の本に「ドキュメントを書くな」と書かれていて、
>>「おや?」と思ったことがあります。
>>「そんなことソース読んだら書いてあるってば」級のドキュメントを
>>延々と書いて結局二重化させるのは無駄以外の何物でもないとは思っていますが、
>>全体を見渡すための概観用の文書とか、
>>言葉の意味を書いた文書とか、
>>知識の共有のための文書は必要なんじゃないかと思うのです。
＜さらに中略＞
>>ただ、よく思うことは、せっかく書いたこういう文書を読みたがらない人が意外と多
>>いということですね。
>
>これはたしかに多いですね。
># と自分を棚に上げて言う(^^;
確かに、ドキュメント書くのはめんどうな仕事ですし、そし
てそのプロジェクトに初めて投入された場合でもないかぎり、
無味乾燥な文章なんて普通はあまり読みたがらないもです。
ようは、いかにして書かせる。または読ませる気にさせるか。
という技巧が必要なのだと思います。
＃ それがむりやりなのか、楽しくなのかは置いておいて。
プロジェクトだと、まず最初に大域的なシステム図(ユース
ケース？)とか書きますけど、それは当然全員読みますよね？
でないと全員の意識合わせができませんし。あまり変更もな
いと思いますし。また、あったらあったでまた意識会わせが必
要ですので。
で、実際コーディングになると、インタフェース(メソッドの
振る舞い)まわりとか気になりだすのですが、XP での開発を想定
すると、そのあたりガンガン変わってしまいますので、そうする
と以前書いた仕様書との差分がどんどん広がっていって、結局ま
ずコード見たりするようになったりする(そして読まない)のです
よね。
それに対抗するにはやはり javadoc のように、説明をソース
コードに直接書き込んで、リバースエンジニアリングで仕様書作
成したりするようなツール作ってみる、などというのはどうでしょ
う？ (別に javadoc そのものでも良いですけど)
なにしろコード上ですから、当事者のプログラマの目にも付き
やすいですし、仕様書の差分も軽減しますから、多少は読んでも
らえるかなと、思うのです。
まぁそれでも、他の人が見てコード読むより楽だ。と思わせる
ことができないとやっぱりなかなか読んでもらえないのですが。
>>そういう人を見ていると、
>>本当に大事な文書って何かとか、
>>どういう文書を書けばみんなに理解してもらえるか
>>という基本的な訓練ができていないような気がします。
>
>そもそも、事実や主張している内容をわかりやすく伝える技術というのが
>日本の国語の教育に欠けていますね。
それは確かにそうだと思います。
しかしまずはどんな文章でも、よく目につく場所において、
無理やりでも読ませる工夫をしてあげないと、せっかくの
苦労が台無しになる気がしています。
ではでは。よしなに。
------------------------------------------------------------
安藤 利和 E-Mail : ando@....jp
http://park.ruru.ne.jp/ando/