问题标签 [documentation]

似乎 C# 3 在我没有注意到的情况下击中了我，你们能告诉我关于 C# 3 的深度指南吗？从 lambda 到 linq，再到该语言第三版引入的所有其他内容。

印刷书籍会很好，但在线指南会更好！

我一直喜欢编写代码文档，但是当涉及到 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 中数据绑定的博客
• 问 WPF 博士
• WPF 导览

链接：

• 微软关于 WPF的 MSDN 动手实验室
• msdn 关于 WPF 入门
• windowsclient.net
• Lernwpf.com
• Codeproject系列文章
• windowsclient.net 上的一些 WPF 视频

演示应用程序：

• 来自 Vertigo 的Family.Show
• 宝贝粉碎

我在一家公司工作，出于某种原因，它坚持我们所有的开发文档都应该是 MS Word 格式。作为二进制格式，这意味着我们不能：

• 文档的不同版本（因此同行评审很痛苦——因为我们工作的领域，所有更改的同行评审都是必不可少的）
• grep 一个包含关键字文档的文件夹

你用什么来写文档，为什么？

也请给我弹药来改变这种情况......

我使用XFire在我的应用程序周围创建一个 web 服务包装器。XFire 在运行时提供 webservice 接口和 WSDL（或者在编译时创建它们，不确切知道）。

我们的许多客户不太了解 Web 服务，而且他们根本不阅读任何外部文档，例如 Javadoc。我知道可以将文档（用于参数和方法）直接添加到 WSDL 文件中。

我考虑过 Annotations 或 Aegis XML 文件，但我不知道如何......你知道方法吗？

编辑：我刚刚发现了这个JIRA 问题，但最后一次活动是 2006 年。有什么想法吗？

许多数据库系统不允许对表和字段进行注释或描述，那么除了具有良好命名约定的明显内容之外，您如何记录表/字段的用途？

（我们现在假设“优秀”的表和字段名称不足以记录数据库中每个表、字段和关系的全部含义。）

我知道很多人使用 UML 图来可视化数据库，但我很少（如果有的话）见过包含字段注释的 UML 图。.sql但是，我在文件中使用注释方面有很好的经验。这种方法的缺点是，.sql当数据库结构随时间发生变化时，它需要手动保持文件是最新的——但如果你这样做了，你也可以让它处于版本控制之下。

我见过的其他一些技术是描述数据库结构和关系的单独文档，以及在 ORM 代码或其他数据库映射代码中手动维护的注释。

您过去是如何解决这个问题的？存在哪些方法以及与之相关的各种利弊？您希望如何在“完美世界”中解决这个问题？

更新

正如其他人所指出的，大多数流行的 SQL 引擎实际上都允许注释，这很棒。奇怪的是，人们似乎并没有过多地使用这些功能。至少不是我过去参与的项目。

对于 ActionScript 2，我使用了 NaturalDocs。但是它对 PHP 的支持很差。到目前为止，我已经看过doxygen和phpDocumentor，但在我看来它们的输出非常丑陋。有人对 PHP 的自动文档生成有任何经验吗？我更喜欢能够使用 javadoc 风格的标签，它们写起来很短，而且很容易记住。

有什么建议可以记录我的 Perl 代码吗？您使用什么以及可以使用哪些工具来帮助我？

您使用哪个模块将 pod 转换为 html？

我有一个包含非常详尽的基于 XML 的文档的程序集，它通过 Sandcastle 用于生成产品的帮助文件。当程序员明显使用程序集时，我们还使用输出 XML 文件在 Visual Studio 中提供适当的 Intellisense。

为了做到这一点，我们似乎同时向用户提供了程序集（“assembly.dll”）和文档（“assembly.xml”）。

是否可以在程序集中嵌入文档，因此我们只需要提供单个程序集文件，Visual Studio 就可以提取信息？也许嵌入为资源或类似的东西？

我是一名 MFC 程序员。我刚刚第一次尝到了 Vista（在 VPC 上……是的，我迟到了）。我应该在未来几天深入评估事情。随便看看，我注意到两个主要变化：

• 外壳是新的
• 用户访问控制
• 事件查看器已更改（希望获得更多信息）

从程序员的角度来看，我还应该注意哪些其他新功能？