自分用のライブラリ記録

Question

趣味で C/C++でやっています。 ( 今回はあまり言語は関係ないですが。一応。 )

皆さんは自分用のライブラリを組んだ場合、

Documentation というのでしょうか?

boost とかについている、

「こういうクラスがあり、こういうメンバ関数 ( メソッド ) がある。
戻り値はこれこれを返す可能性があり、もし失敗すればこういう例外を投げる可能性がある」

みたいなやつありますよね?

そういったのはどうしていますか?

たとえば「 HTMLファイルに記録している。」とか、

「Documentation? そんなもの作るより普通にヘッダファイルなりcppファイルなり直接読むね。」とかです。

私は自分が使いやすいように クラス化 ( あるいは関数化 ) して自分用のライブラリを作成しています。

たとえば、C言語 の FILEポインタを使ってファイルの入出力をする場合を考えてみます。

fopenでファイルを開く -> ファイルのデータを読み込む -> fcloseでファイルを閉じる

のような操作が煩わしいのでクラス化するみたいな感じだとします。

CIoFileクラスなるものを作って コンストラクタでファイルを開いて デストラクタでファイルを閉じる...みたいな。

定義とかのようなプログラム自体は今回の場合は問題でないのでスルーします。

私が聞きたいのは、

この CIoFileクラスのコンストラクタで引き受ける引数、投げられる例外,
メンバ関数はどういうのがあり...

というのをどこに記述するかです。

ソースコードにではなくて、「あー、CIoFileっていうクラスあったけど、引数どんなだったかな? 例外投げたっけ?」とかみたいに

ド忘れしたりしますよね。

その対策というか、Documentation があったらそれでチェックできると思うので。

ただ、HTMLでやると いちいちクラスごと ( あるいは関数ごと ) に 立てる必要があるのでどうなのかな... と。

Word を使って HTML っていう方法もありますが、一ページごとに "ディレクトリ" ができますし...

皆さんはどういう風にやっているのでしょうか?

ベストアンサーは、試してみたいと思う方にする予定です。

宜しくお願い致します。

Answer 1

私はヘッダーにDoxygen形式でコメントを書いています。
Doxygenというツールを使うとソースのコメントからHTMLなど（形式はいくつか選択可能）のドキュメントを作成できます。ソースファイル内にドキュメントを書くのでメンテナンスが集約でき、ソースとドキュメントの乖離をなくすことができます。リファレンスマニュアルの作成にとても便利です。

Comments

[Take-y]

確かにソースとドキュメントの乖離はよく発生しますね。
修正ルールを明確にして徹底して、ツールで出力するようにすれば
乖離をなくすことができるので、いいですね。

[WoodenHamlet]

出力形式が多いのも良いですよね。

Answer 2

こんにちは。

私は基本的にソースのコメントに書きます。ソースを読んだだけでは理解するのがたいへんな内容をコメントに書くよう努力してます。（なかなか十分にはできてませんが。）
逆に、ソースを見れば直ぐに分かることは省略することが多いです。

「あー、CIoFileっていうクラスあったけど、引数どんなだったかな? 例外投げたっけ?」

通常はソースとコメントを見ます。
ドキュメントとソースを同期させる苦労は半端ないです。機能テスト完了時点でソースの修正をドキュメントへ反映するのが一番手間が掛からないと思いますが、開発～機能テストまでの期間が空くことも有ります。かと言って変更する度に反映すると、その後の工程で再変更も多発するため、ついサボって反映漏れします。あてにならないドキュメントは無い方が良い場合も少なくありません。

内部I/Fはお手軽に修正できる姿を保つべきですので、強い理由がない限りドキュメント化はしないことにしました。

---

【蛇足ですが】
社外へ公開するI/Fは外部仕様書として書きます。昔はMS-Wordを良く使ってました。

最近、やっとDoxygenを使うようになりました。
Doxygenは主にリファレンスを書く時用のツールですが、外部仕様書も書けます。
リンクをお手軽に貼れたり、ソースをプロジェクト内から引っ張ってきてドキュメントへ埋め込んだりできるので便利です。
表は書けますが図を書けない点や細かい見栄えの調整が難しい点はMS-Wordに劣りますが、ソースを修正した時、ドキュメントへ自動反映される部分も多く、プログラムのドキュメントを書くのにはかなり強力なツールと思います。
図が必要になることは少ないのでどうしても必要な時はdraw.ioでひょひょいと書いて貼り付けてます。MS-Wordで書く時より細かい調整はし辛いですが、よりお手軽に必要な図を描けます。

Answer 3

実際、開発プロジェクトの中でもそれぞれ違うと思いますが、過去経験した
簡単なドキュメント管理を例に挙げると、Excelの1シート1関数でリファレンスを
記述、目次シートを作って関数名をリファレンスシート(ブック)のリンクにして
参照しやすくしているものがありました。
元々、紙文化のプロジェクトだったので、印刷することも目的に入ってましたが、
目次シートに関数名や概要まで記載してあれば、目的の関数を探しやすいという
メリットはありました。ただ、例えば「例外を投げている関数」とか条件で検索
したい場合は非常にめんどくさいです。
色々と利便性を考えると、DBにテーブル作って専用アプリを作成して参照、検索
できるようにするのがいいのかもしれません。