如何在编程时编写文档

Question

您是否有这样的习惯，即当您编写 时，您还要编写 文档，并确保 表示它们同步。

如何才能实现 那？你写下什么？ 功能逻辑？这个概念？或 其他最佳做法？感谢 提前！

Answer 1

我是一名python程序员，我写了很多doctests，它是一个python模块，它允许您在每个函数的文档字符串中编写测试作为函数用法的示例。有一个在该示例从here：

def factorial(n): 
    """Return the factorial of n, an exact integer >= 0. 

    If the result is small enough to fit in an int, return an int. 
    Else return a long. 

    >>> [factorial(n) for n in range(6)] 
    [1, 1, 2, 6, 24, 120] 
    """ 

最后两行是功能的使用的一个例子，并且可以使用文档测试模块来执行。这样，你完成了：

• 你把这个函数的用法的例子，所以你的用户将知道如何使用它;
• 如果您在测试套件中包含测试并经常运行测试，那么您将会注意到，如果示例因代码更改而中断
• 不需要太多时间来编写这些示例。

我通常从创建存根函数和编写文档测试开始，了解每个函数的工作方式以及期望的输入/输出;感谢这种方法，我总是至少有一个关于我写的每个函数和模块的简短文档。

我不时编写一篇较长的文档，解释如何使用我的模块（对于我的同事），而且我总是使用doctest语法;然而，重新提出你的问题，我从来没有做过比这更多的事情，有时我可以在我的作品或我写的图书馆上写博客评论，但我没有时间写更长的文档。

Answer 2

我不这样做，但您可以使用XML注释语法来帮助实现它。它可以让你至少记录你的类，属性和方法调用。然后，您可以使用构建自动化为您构建CHM文件。为此调查沙堡。

否则，有助于跟踪团队协作的wiki也很有用。这些东西常常变成“信息池”，人们在这里描述系统的一些信息。这些也可以用来构建文档。

最后，如果您已与跟踪商店进行了整合，则可以构建发布说明。例如，TFS可让您获取任何给定构建的所有工作项和变更集，这对构建发行说明非常有用。

Answer 3

我在开始之前编写文档结构并在写作时对其进行更改。我用契约式设计的结构如何在文档中写：

http://en.wikipedia.org/wiki/Design_by_contract 

• 可接受和不可接受的输入值或类型，以及它们的含义
• 返回值或类型，以及它们的含义
• 错误和可能发生的例外情况值或类型，以及它们的含义
• 副作用
• 先决条件，哪些子类可能会削弱（但不会增强）
周
• 后置条件，其子类可以加强（而不是削弱）
• 不变，其子类可以加强（而不是削弱）
• （比较少见）履约担保，如用于时间或空间

Answer 4

这些东西应该在设计规范（取决于问题领域）最好。剩下的我喜欢用特定的代码编写代码，然后自动创建文档。一个很好的工具是doxygen，但还有很多。

这种方式的文档几乎是自动完成的，因为我喜欢在我的工作中评论我的代码。

Answer 5

这取决于文档的上下文。如果您正在为其他开发人员编写文档，那么我会认为体面的单元测试和带有注释的变量命名，然后代码将自行记录。

在客户使用的外部API的上下文中，我通常会在写完该功能后采取记录该项目的方法。

Answer 6

1. 使代码的自我记录越好 -
2. 简单和容易的电子
3. 抢文档画图声音咬不杂文 - 比如使用一个内部博客/维基等抢的屏幕截图和思想信息。思维导图帮助

这可以帮助我记录下我的情况。

实质上是一些简单的工具来收集想法，然后在需要时可以很容易地将它们放入更大的文档中。使用好的工具我使用livewriter，mediwiki，snagit，onenote和freemind。

我讨厌写文档 - 所以我一直在收集想法。

Answer 7

写得不错，写得很好的代码应该不需要太多额外的程序员文档。至于最终用户文档，我在实现每个功能的同时为我的appliocations编写帮助文件，并在完成大部分编码时编写教程。不过，我认为在这个过程的早期编写教程会是一个更好的主意。