ドキュメントを書くこと

外注さんに、ウチの会社に常駐して仕事をしてもらった。
2週間ほどだったけれど、お嬢さんがバイオリンを習っているとかで、意気投合し、なかなか楽しくお仕事させて頂いた。
休日出勤などの無理も聞いて頂いて、大変頑張って間に合わせて下さった。
ウチの会社に納入してもらう時に、受入検査というのがあるのだが、そこでドキュメントをチェックしていて、大変面食らった。
全然意味がわからない。

私  :「えーっと、『CDで対応する』って言うのは、『CDからコピーする』って意味ですか?」
外注さん:「はい、CDから対応するって意味です。」
私  :「こっちの『アーカイブで対応する』って言うのは、『アーカイブのtar-ballを解凍する』って意味ですか?」
外注さん:「はい、アーカイブで対応するって意味です。」

上記のようなやりとりを、この後、十回以上繰り返した。
私が何故質問したのかも、全然わかって頂けていない様子。
忙しいところ申し訳なかったのだけど、全然わからないので、外注さんに質問しながら全部赤を入れて、書き直して頂いた。
私は良いけれど、他の人には、絶対にわからないだろうなぁと思ったので。

うーん。
美文である必要は全然ないけれど、わかりやすいドキュメントが書けなくてはいけないなぁと、つくづく思ってしまった。
プログラマは、処理速度の速いソースやメモリ使用効率の良いソースを書ける事、早くコーディングできる事ばかりが重視される傾向にあると思うけれど、それ以外にも、わかりやすいドキュメントが書けるということも、結構大事だと思う。
自分で書いたものを客観的に見るのは、とても難しい。
他の人に読んでもらって、チェックしてもらえると一番良いのだけど、そうもいかない場合が多い。
私も気をつけなくては。
[PR]
Commented by itchys at 2004-03-12 19:20
 やっぱり分かりやすいドキュメントを書けるって事はその時点
で既に分かりやすいプログラムが出来上がることを保証されて
いるのかも、と思います。

 自分なんて趣味で短いプログラムを組んでみても、俗に言う
「スパゲッティ・コード」(中身グチャグチャ)を組んで
しまいます、論理的思考が出来てないんだろうなぁ(汗
Commented by xiaoxia at 2004-03-12 19:25
なるほど、どちらも論理的思考ですもんね。ってことは、ステキなドキュメントが書けるようになると、おのずと、ステキなコードが書けるようになるのかもしれませんね。むむむ。
Commented by jmoki at 2004-03-12 20:45
これ、とっても賛同できます。人にわかりやすいドキュメント書くのは本当に難しいですね。そう、人が書いたものをチェックするのはできますが、自分で書いたものをチェックしてもわからなかったりしますしね。
良いプログラマとは、わかりやすい文書、コードを書ける人だって思います。どんなに動かしたら処理能力があるプログラムだったとしても、その作った人しかわからないコードだったりしたら良いプログラムだって思えないかなって。
Commented by xiaoxia at 2004-03-12 20:56
それはしみますね。
自分のためだけのプログラムなら構いませんが、仕事となると、他の人が手をいれる可能性が大きいですから、可読性は本当に大事ですよね。
アマチュアプログラマでも、コーディング能力の高い人はいますが、その点をどのくらい重視するかが、プロとの違いだと思っています。
Commented by sprewell8_daisuki at 2004-03-13 09:28
まったくもって同意。
つーか、最終的に仕事をするのは人と人なので、「他人が分かる」って言うのが最大のポイントとなりますよね。
ドキュメントでも会話でもコードでも、その情報を発した本人にしか分からなかったら、それってもうすでに「情報」じゃないと思います。
ついでに言うと、大学で高度な論理を学んだ人より、会社に入ってから覚えた、みたいな人のほうが、可読性を分かっている気がします。
Commented by maida01 at 2004-03-14 08:05
文章が下手で反省しています。何回読み直して修正していますが、暫くして読みなおすと、意味不明なことが多いです。
昔プログラミングをしていた頃は、プログラミング自身が好きではなかったので、単純なプログラムで判りやすいと言われたのですが。
Commented by xiaoxia at 2004-03-15 13:31
>> sprewell8_daisukiさん
そう、人と人で仕事をしているんですよね。コンピュータの相手してばかりいるから、忘れそうですが。学校と会社は人の育て方(目的)が違うので、おのずと違いが出てくるんだと思います。
>> maida01さん
妙な方向に凝ろうとしなかったのが、却って良い結果になったのですね。なるほど。テクニックが付いてくると、使いたくなってしまうのがサガではありますが、良し悪しなのですね。
Commented by ja_guar at 2004-03-15 14:31
コメントをつけなくてもプログラム自体がコメントと同等、つまり誰が読んでもわかりやすいソースを書くことが目標、といってました。(誰が(笑))

私はコメント入ってないプログラムにはぶち切れです(笑
Commented by xiaoxia at 2004-03-15 18:09
コメントが要らないソースとは、これまたステキですね。
ちゃんと意味のあるコメントならOKですが、意味の無いコメントは、入っていると、却ってブチ切れたくなります(^^;;
Commented by fireorsky at 2004-03-25 02:53
プログラマが苦手な言語は・・・、概して「日本語」だと思いますよ。^^;
Commented by xiaoxia at 2004-03-25 13:52
fireorskyさん、いらっしゃいませ。
おおっ、それは真実ですね! 今度どこかで使わせていただきます(笑)
プログラム言語の方が多義が出ませんから、独りよがりな言葉にならないで済むんですよね。
by xiaoxia | 2004-03-12 17:37 | コンピュータ関係 | Comments(11)

ダメ女プログラマ&主婦&腐女子&バイオリン弾き


by 小霞