問題タブ [documentation]

C# 3 は私が気付かないうちに私を襲ったようです. C# 3 の詳細なガイドについて教えていただけますか? lambda から linq まで、言語の 3 番目のバージョンで導入されたその他すべてのもの。

印刷された本もいいでしょうが、オンライン ガイドはさらに優れています。

私は常にコードのドキュメント化に取り組んできましたが、AJAX + PHP となると、必ずしも簡単ではありません。コードは本当に散らばっています。ロジック、データ、プレゼンテーション (名前を付けます) は、サーバー側とクライアント側のコードの間で分割され、混合されます。作業の一部を実行するデータベース側のコード (ストアド プロシージャ、ビューなど) が存在する場合もあります。

これは、そのようなコードを文書化するための効率的な方法を考え出すことに挑戦します。私は通常、.php ファイル内の .js ファイルのリストと、.js ファイル内の .php ファイルのリストを提供します。また、インライン コメントと関数の説明も行います。ここでは、どの関数がどのファイルで使用され、どのような出力が期待されるかをリストします。データベース プロシージャについても同様のタスクを実行します。多分もっと良い方法がありますか？

アイデアや経験はありますか？

注: この質問は、Javascript+PHP だけでなく、あらゆるクライアント + サーバー側アプリケーションに適用されます。

私は WPF にまったく慣れていないので、最初に役立つクイックスタート ドキュメントを探しています。Adam Nathan の WPF Unleashed という本を購入しますが、これはクイック スタートというよりはリファレンスだと思います。
お気に入りのリンクや書籍、wpf 開発に関するデモ アプリケーションを教えてください。

回答の焦点は、ベスト プラクティス、読みやすい紹介 (私は msdn のリンク ファームが嫌いです ;)、および包括的な参照にある必要があります。

編集: タイプ別にソートされた短いリストにすべての提案を集めようとします。そして、そのリンクやその本を特別にお勧めする理由を簡潔に述べてください。

書籍:

• Adam Nathan によって解き放たれた WPF
• Pro WPF: .NET 3.0 の Windows Presentation Foundation
• Chris Sells と Ian Griffiths による WPF のプログラミング

ブログ:

• Beatriz Costa による WPF でのデータ バインディングに関するブログ
• Dr.WPFに聞く
• WPF のガイド付きツアー

リンク:

• WPF に関する Microsoftの MSDN ハンズオン ラボ
• msdn で WPF の使用を開始する
• windowsclient.net
• Lernwpf.com
• Codeproject に関する一連の記事
• windowsclient.net の WPF ビデオ

デモ アプリケーション:

• Family.Show from Vertigo
• ベイビースマッシュ

私は、何らかの理由で、すべての開発ドキュメントをMSWord形式にする必要があると主張する会社で働いています。これは、バイナリ形式であるため、次のことができないことを意味します。

• ドキュメントのバージョンを相互に比較します（したがって、それらをピアレビューするのは面倒です-私たちが取り組んでいるドメインのため、すべての変更に対するピアレビューが不可欠です）
• フォルダをgrep-キーワードのドキュメントでいっぱい

ドキュメントを書くために何を使用しますか、またその理由は何ですか？

この状況を変えるための弾薬もください...

XFireを使用して、アプリケーションの周りにWebサービスラッパーを作成します。XFireは、実行時にWebサービスインターフェイスとWSDLを提供します（またはコンパイル時に作成しますが、正確にはわかりません）。

お客様の多くはWebサービスをよく知らず、さらにJavadocなどの外部ドキュメントを読んでいません。（パラメーターとメソッドの）ドキュメントをWSDLファイルに直接追加できることを知っています。

AnnotationsまたはAegisXMLファイルについて考えましたが、方法がわかりません...方法を知っていますか？

編集：このJIRAの問題を見つけましたが、最後のアクティビティは2006年でした。何かアイデアはありますか？

多くのデータベース システムでは、テーブルやフィールドのコメントや説明を許可していません。では、テーブルやフィールドの目的を文書化するには、適切な命名規則を使用することは別として、どうすればよいでしょうか?

(今のところ、データベース内のすべてのテーブル、フィールド、および関係の完全な意味を文書化するには、「優れた」テーブル名とフィールド名では不十分であると仮定しましょう。)

多くの人がデータベースを視覚化するために UML ダイアグラムを使用していることは知っていますが、フィールド コメントを含む UML ダイアグラムを見たことはほとんどありません。.sqlただし、ファイル内でコメントを使用した経験は豊富です。このアプローチの欠点は.sql、データベース構造が時間の経過とともに変化するにつれて、ファイルを手動で最新の状態に保つ必要があることですが、そうする場合は、バージョン管理下に置くこともできます。

私が見た他のいくつかのテクニックは、データベースの構造と関係を説明する別のドキュメントと、ORM コードまたはその他のデータベース マッピング コード内の手動で維持されたコメントです。

過去にこの問題をどのように解決しましたか？どのような方法が存在し、それらに関連するさまざまな長所と短所は何ですか? 「完璧な世界」でこれをどのように解決しますか?

アップデート

他の人が指摘しているように、一般的な SQL エンジンのほとんどは実際にコメントを許可しています。これは素晴らしいことです。奇妙なことに、人々はこれらの機能をあまり使用していないようです。少なくとも、私が過去に関わったプロジェクトではそうではありません。

ActionScript 2 では、NaturalDocsを使用しました。ただし、PHP のサポートはかなり貧弱です。これまでdoxygenとphpDocumentorを見てきましたが、私の意見では、それらの出力はかなり醜いです。PHP の自動ドキュメント生成の経験がある人はいますか? javadoc スタイルのタグを使用できるようにしたいと考えています。これらのタグは、記述が短く、覚えやすいものです。

Perlコードを文書化する方法について何か提案はありますか？何を使用し、どのツールを使用して私を支援できますか？

ポッドをHTMLに変換するためにどのモジュールを使用しますか？

非常に完全なXMLベースのドキュメントを含むアセンブリがあります。これは、Sandcastleを介して製品のヘルプファイルを生成するために使用されます。また、プログラマーがアセンブリを明らかに使用する場合、VisualStudioで適切なIntellisenseを提供するために出力XMLファイルを使用します。

これを行うために、アセンブリ（ "assembly.dll"）とドキュメント（ "assembly.xml"）の両方をユーザーに提供しているようです。

どういうわけか、ドキュメントをアセンブリ内に埋め込むことができるので、単一のアセンブリファイルを提供するだけで、Visual Studioは情報を抽出できますか？たぶん、リソースなどとして埋め込まれていますか？

私は MFC プログラマーです。Vista を初めて味わったところです (VPC で... うん、遅れました)。私は今後数日間で物事を深く評価する必要があります. さりげなく見てみると、2 つの大きな変更点に気付きました。

• シェルは新品です
• ユーザー アクセス制御
• イベント ビューアーが変更されました (これに関する詳細情報が必要です)

プログラマーの観点から、他に注目すべき新機能は何ですか?