使用PHP的大型或小型项目的文档？

Question

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

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

到目前为止我的想法：

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

某种纸/ wiki ..有关基础设施的信息（数据库，防火墙......）

如果你必须将你的项目移交给其他人（在php中可能不如你），你还提供了什么呢？

您是否创建了“添加函数来读取服务器数据，放入Model xYZ？”

抱歉我的英语不好：）

Answer 1

你应该考虑使用它们全部三个。

尽量不要使文档过于复杂化：更难以使其保持最新，更有可能无法维护。恕我直言，将代码库引入新程序员的最低要求是编码指南（如何调用变量，如何调用类，使用匈牙利语符号？）和phpdoc。如果您的代码大量使用第三方库和大型配置文件，请编写一个小PDF，其中包含使您的代码在裸​​机上运行的步骤。

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

即使考虑到这些，在将代码库放弃到新的编码器之后，也要经常打电话。对你来说似乎合乎逻辑且清晰的可能不适合新人。

Answer 2

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

每当我加入一个新项目时，我一直需要的一件事就是知道代码的位置以及如何访问它。将代码行匹配到正常运行的开发或暂存环境，可以快速地试验和发现以前开发人员的“模式”。

如果我可以在界面中进行小的调整，那么我已经破解了螺母，并且可以开始朝着数据的方向前进。

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

Answer 3

如果项目有API，那么我可能会提供样本用法，示例等。

Answer 4

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

我通常会发现api文档对于构建新功能很有用，但对于查找错误并不是特别有用，这只能通过内联注释来解释。

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

是的，我是一个称职的程序员，但是代码库的大小和复杂性以及大多数代码都是由其他人创建的事实意味着我经常要向他寻求有关潜在bug漏洞的解释。因此，如果你真的投入使用后继续使用代码库，请考虑尽可能将自己作为资源使用。

我认为必不可少的最后一件事是git（或mercurial，或其他一些DVCS），用于记录性提交历史记录和potential web-interface代码可以随附的代码。