使用 PHP 的大型或小型项目的文档？[关闭]

Question

目前我们正在谈论很多关于程序员的文档。你如何处理这部分？

将新团队人员引入“大型”PHP 项目的最佳方法是什么？新人需要什么？

到目前为止我的想法：

• 好的源代码
• 通过phpdoc生成的api文档
• 清晰的编码风格/指南

某种论文/维基..有关基础设施的信息（数据库、防火墙......）

如果你必须把你的项目交给别人（可能不如你的php），你还能提供什么？

您是否创建类似“添加读取服务器数据的功能，放入模型 xYZ 中？”的内容？

抱歉我的英语不好:)

Answer 1

您应该考虑使用所有这三个。

但是，尽量不要使您的文档过于复杂：保持最新状态越困难，就越有可能得不到维护。恕我直言，向新程序员介绍代码库的最低要求是编码指南（如何调用变量，如何调用类，是否使用匈牙利表示法？）和 phpdoc。如果您的代码大量使用第三方库和大型配置文件，请编写一个小 PDF，其中涵盖使您的代码在裸​​机、新机器上运行的步骤。

如果您正在使用单元测试，也请记住记录这些测试。

即使考虑到这些，在将代码库交给新编码员之后，预计会经常接到电话。对你来说看似合乎逻辑且清晰的事情可能并不适合新人。

Answer 2

文档很好 - 但请将其视为指南。它不应该是为了教授编程而编写的，也不应该是一个很容易过时的文档。

每当我加入一个新项目时，我始终需要的一件事就是知道代码所在的位置以及如何访问它。将代码行与功能开发或暂存环境相匹配，可以快速打开实验和发现以前开发人员的“模式”的大门。

如果我可以在界面中进行一些小的调整，那么我就已经解决了问题，并且可以开始向后处理数据。

但后来我习惯了参与很少或没有文档的项目。并不是每个人都对此感到满意。

Answer 3

如果项目有 API，那么我可能会提供示例用法、示例等。除了其他人。

Answer 4

我为一个中等规模的代码库编写代码，该代码库几乎完全是唯一其他程序员（我是新人）工作的产物。我们拥有来自 API phpdoc 注释和版本控制内最佳实践文本文件的自动美化文档。我会放弃这两个，因为：更广泛的内联评论和某种自动化测试。

我通常发现 api 文档对于构建新功能很有用，但对于寻找错误并不是特别有用，只有通过内联注释才能真正很好地解释这一点。

因此，在我自己的工作中，我尝试在接触代码行之前在注释中列出新代码的行为。我也想转向测试驱动设计，但还没有真正做到这一点。

是的，我是一名称职的编码员，但是代码库的大小和复杂性以及大部分代码是由其他人创建的事实意味着我经常必须向他寻求关于潜在错误来源的解释。因此，如果您真的投入了精力让代码库在您离开后继续存在，请考虑在可能的情况下将自己作为一种资源。

我认为重要的最后一件事是 git （或 Mercurial，或其他一些 D.V.C.S.），用于记录提交历史记录和 潜在的网络界面 到它们附带的代码。