質問をすることでしか得られない、回答やアドバイスがある。

15分調べてもわからないことは、質問しよう!

ただいまの
回答率

90.53%

  • C

    4394questions

    C言語は、1972年にAT&Tベル研究所の、デニス・リッチーが主体となって作成したプログラミング言語です。 B言語の後継言語として開発されたことからC言語と命名。そのため、表記法などはB言語やALGOLに近いとされています。 Cの拡張版であるC++言語とともに、現在世界中でもっとも普及されているプログラミング言語です。

自分用のライブラリ記録

解決済

回答 3

投稿

  • 評価
  • クリップ 0
  • VIEW 418

BeatStar

score 1221

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

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

Documentation というのでしょうか?

boost とかについている、

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

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

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

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

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

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

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

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

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

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

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

私が聞きたいのは、

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

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

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

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

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

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

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

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

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

宜しくお願い致します。

  • 気になる質問をクリップする

    クリップした質問は、後からいつでもマイページで確認できます。

    またクリップした質問に回答があった際、通知やメールを受け取ることができます。

    クリップを取り消します

  • 良い質問の評価を上げる

    以下のような質問は評価を上げましょう

    • 質問内容が明確
    • 自分も答えを知りたい
    • 質問者以外のユーザにも役立つ

    評価が高い質問は、TOPページの「注目」タブのフィードに表示されやすくなります。

    質問の評価を上げたことを取り消します

  • 評価を下げられる数の上限に達しました

    評価を下げることができません

    • 1日5回まで評価を下げられます
    • 1日に1ユーザに対して2回まで評価を下げられます

    質問の評価を下げる

    teratailでは下記のような質問を「具体的に困っていることがない質問」、「サイトポリシーに違反する質問」と定義し、推奨していません。

    • プログラミングに関係のない質問
    • やってほしいことだけを記載した丸投げの質問
    • 問題・課題が含まれていない質問
    • 意図的に内容が抹消された質問
    • 広告と受け取られるような投稿

    評価が下がると、TOPページの「アクティブ」「注目」タブのフィードに表示されにくくなります。

    質問の評価を下げたことを取り消します

    この機能は開放されていません

    評価を下げる条件を満たしてません

    評価を下げる理由を選択してください

    詳細な説明はこちら

    上記に当てはまらず、質問内容が明確になっていない質問には「情報の追加・修正依頼」機能からコメントをしてください。

    質問の評価を下げる機能の利用条件

    この機能を利用するためには、以下の事項を行う必要があります。

回答 3

checkベストアンサー

+6

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

投稿

編集

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

  • 2017/02/02 11:29

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

    キャンセル

  • 2017/02/02 13:02

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

    キャンセル

0

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

投稿

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

0

こんにちは。

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

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

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

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


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

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

投稿

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

同じタグがついた質問を見る

  • C

    4394questions

    C言語は、1972年にAT&Tベル研究所の、デニス・リッチーが主体となって作成したプログラミング言語です。 B言語の後継言語として開発されたことからC言語と命名。そのため、表記法などはB言語やALGOLに近いとされています。 Cの拡張版であるC++言語とともに、現在世界中でもっとも普及されているプログラミング言語です。