ぼんやりと考えている人

ひろしまなおき (廣島直己)
名前: ひろしまなおき (廣島直己)
住処: シリコンバレー
職業: しがないプログラマ
家族: 愛妻一人、息子一人、娘一人
道具: ハーレー二台、ギター三本
電紙: n at h7a.org

Twitter

« August 2019
S M T W T F S
        1 2 3
4 5 6 7 8 9 10
11 12 13 14 15 16 17
18 19 20 21 22 23 24
25 26 27 28 29 30 31

以前にぼんやりと考えたこと

最近のコメント

  • ひろしま (ひらがなせいかつ …): じゅくじくんは なくした ほうが いい ですね。ぼくは…
  • たんぽぽ (ひらがなせいかつ …): きゅうに ぜんぶの ことばを ひらがなだけに する…
  • とね まさひこ… (ひらがなせいかつ …): ぼくは ものかき だが, かんじが きらいなので,…
  • とりえ (ひらがなせいかつ …): このさいとは みているだけで なんとなく ほんわか…
  • ひろしま (思い通りの日本語…): こうどな ほんを よめなければ、こうどな たんごを 学…
  • nt4 (思い通りの日本語…): ひらがなせいかつに初めて接し、興味を覚えました。そ…
  • ひろしま (ひらがなせいかつ …): やはり、がいこくに くらしていたり、がいこくとの か…
  • ぷりうりうぷ… (ひらがなせいかつ …): こんにちは。すうぇーでんに すんでいます。いとうさ…
  • Joi Ito (ひらがなせいかつ …): もと べいにち たいしの Edwin O. Reischauer さん…
  • yonay (理屈じゃないとい…): なんか、著者の主張を誤解しているような気がするよ。…

  • Powered by Pivot - 1.40.5: 'Dreadwind'
  • SPAM Poison
  • XMLフィード(RSS 1.0)
  • Atomフィード

29 September '2003 - 23:35 | 雑記 一石二鳥。

「ドキュメントはソースです。バグも書いてありますし。」 こう言えたらいいのだけれど、そうは問屋が卸さない。

自分が仕事用に開発したライブラリがいくつかあるのだが、主に自分がかかわるプロジェクトでメインで使うライブラリだし、社内でこのライブラリを使う人たちは、自分ともプロジェクトの関係が近い人が基本だから、ドキュメントは適当にでっち上げたのしかなく、しかも、どうしようもないことに、ドキュメントはあまりまじめに保守してなかった。

が、しかし、どうも、最近、それを売ってくれという話が来たりするようになった。

ただ、ライブラリそのものを売ることを前提には書いてないし、ドキュメントも不備だったりして、正直、面倒くさいなぁ、とは思うのだが、欲しい人を探して売ってしまうというのは、商売として正しいし、エンジニアとしてはセールスの人の言うことを聞くしかない。

というわけで、ドキュメントの保守をちゃんとすることにしたのだけれど、まじめにやるとなったら、やっぱり、JavaDoc みたいな方向がいい。これなら、ちょっとだけまじめやれば整合性は完璧だし。

で、書式を覚えるのも面倒だし、方向だけでなく、書式も JavaDoc のまま、もしくは類似のものがいいなぁ、ということで探してみた。

すると、C++ で使えるものは多いんだけれど、C でもいいよ、というのはほとんどない。また、C で使えるんだけれど、書式は独自というのがほとんど。

おれが書いてるライブラリは全部 C で書いてるので、JavaDoc みたいなスタイルというと、実はそんなになかったのだった。

結局 Documentation Tools を参考にして、Doxygen を使ってみることにした。使ってみたら、これがなかなかいい。かなり気に入った。

こいつの存在自体は前から知ってんだけれど、あまり興味をもってなくて何も調べてなかった。不覚すぎ。

さて、こうなると、既存のライブラリのドキュメントを一新したくなる。まぁ、基本的なことはそもそもソースにもちゃんと書いているので、それを元にフォーマットを合わせればいいだけなので、言うほどひどい仕事ではない。

が、しかし、こういう面倒なことは、スクリプトを書いて計算機にやらせてしまうか、やらせることで経験値をあげることができそうな若者にやらせてしまうのが、おれ流。

そして、ちょうどいいところに、理解させとくと後でおれが楽できそうだ、というヤツがいたので、そいつにやらせることにした。「まず、このライブラリが何をやってるのか、完璧に理解し、そして、ちゃんと理解したことを証明するために、Doxygen で素晴らしいドキュメントが生成されるようなコメントを書いてみろ」と指示。

いやぁ、労せずして、それなりのドキュメントが出来上がってきて嬉しい、嬉しい。

そいつがコメントを入れる過程で散々質問攻めにあったおかげで、そいつのコード、プロトコル、仕様などの理解度もよく把握できたし、ついでにいろいろと教えてやることもできたし、ほんと、一石二鳥とはこのことだ。

Trackback link:

トラックバック用URLを生成するには、JavaScriptを有効にしてください。



  
情報を記憶する

Emoticons /

酢ハムがいったいどんなハムなのかはともかく…
 

 

通知:
非公開:

注意: 使用できるタグは <b> と <i> のみです。URLやメールアドレスはそのまま記述すればリンクになります。