1

ミドルウェア/SDK/ライブラリ、またはプログラミング手法など、学習目的で非常に具体的な方法を示すサンプルプログラムを[ゼロから作成、リライト、リファクタリング]する必要があるとします。

サンプルプログラムをどのように文書化しますか？

SDKサンプルを完全に書き直しても、広範なコメントがあっても、高レベルのメタドキュメントやコメント、またはそれと呼べるものが必要だと感じたので、私はそれを求めています-何を説明している概要ページプロジェクトについてです。

  • すべてのサンプルプログラムのREADMEファイルでその作業を実行できますが、たとえばWikiのフォーマットが適切ではありません。

    • 長所：シンプル
    • 短所：単純すぎます。ソースファイルの一部ではありません。

  • Doxygenコメント：各プロジェクトがDoxygenで生成された「メイン」ページを出力する方法でdoxygenコメントを書くことは可能だと思いますか？

    • 長所：ソースファイルの一部。（可能であれば）便利なハイパーリンクされたドキュメントのメインページ。
    • 短所：私が考えることができるものはありません

  • バージョン管理システム+TRACチケット/wikiシステム：プロジェクトにSubversionを使用しているので、SVNリポジトリと一緒にTRACをインストールすると、サンプルプログラムを文書化できるように見えますが、これがやり過ぎかどうかはわかりません。私は作業環境でTRAC+Subversionを使用したことがなく、TRAC + Subversionの使用ワークフロー、通常チケット、ウィキページに記載されているもの、これらすべてが特定のリビジョンに「接続」されている方法がわからないためです。文書化する必要のあるプログラムの

    • Subversionリポジトリに加えてTRACを使用するという（おそらくワイルドな）アイデアは理にかなっていますか？または、SVN + TRACを使用したワークフローの要点と基本を完全に見逃していますか？
    • 長所：機能が豊富
    • 短所:(多分）セットアップとメンテナンスのやり過ぎ
4

2 に答える 2

1

私はソースのドキュメントを好む傾向があります。これにより、発見され維持される可能性が高まると思います。私のJavaの世界では、パッケージレベルの概要資料を含め、ソースから抽出できる非常に優れたJavaDocを作成できます。

そこに、またはアプリケーションへの主要なエントリポイントに、説明的な概要資料を追加します。ここで、私の「メイン」は、ある場合です。

実際にソースディレクトリにあるREADME.txtもSCMに組み込まれるので、これも機能しますが、プログラムの残りのドキュメントと何らかの形で統一することをお勧めします。

于 2009-08-30T20:56:57.037 に答える
0

可能であれば、最も一般的なシナリオを考えて、それぞれに単純な（理想的には別々の）サンプルを提供します。新しいSDKを使用することは、私のニーズとは関係のない1つまたは2つの非常に具体的なことを行うため、非常にイライラすることがよくあります。そのため、開始方法については暗闇にさらされています。

ドキュメントに関しては、サンプルコードがきれいなコーディングスタイルであり、コメントが適切であることを確認することから始めます（コーディング中に読み取ることができるコード内コメントとDocXml / Doxygen関数コメントの両方、および/または外部で読み取り可能なものに抽出することができます）フォーマット）。これ自体は、優れたプログラマーがサンプルを理解できるようにするのに十分なはずです（つまり、クラスのコメントは、単語の間にスペースを入れてクラスの名前を含めるだけでなく、クラスが使用される方法/場所/理由を説明する必要があります！）

次に、クイックスタートガイドやサンプルの概要を追加します。PDFは、優れたフォーマットを使用でき、簡単に読み取って印刷できるため、適切なフォーマットになります。あなたは概要が有用であることについて正しいです。エンドユーザーの観点から考えてみてください。「このSDKを見たことがないので、XYZを実行したい。最初にどこを見ればよいのか、どのような重要な概念を理解する必要があるのか​​」。

覚えておくべき主なことは、SDKを使おうとしている人は、これまでSDKを使用したことがないということです。したがって、説明では事前の知識を前提とせず、基本をカバーする必要があります。これは、ほとんどのSDKドキュメントが当てはまるところです。作成者はSDKの使用の専門家であり、読者の理解をはるかに超えるレベルで飛躍します。または、すべてを文書化するため、エンドユーザーは数千のAPI呼び出しに関する情報でいっぱいになりますが、開始するために最初に呼び出すAPI呼び出しがわかりません。多くの場合、1つの文で、サンプルやドキュメントを調べて、物事がどのように機能するかを理解するために何時間も何日も費やすことができます。

于 2009-08-30T21:08:03.847 に答える