Php 记录+；追溯评论

我即将完成一个为期9个月的马拉松项目——一个拥有超过7万行代码的web应用程序。问题是我很少使用注释，从未使用过javadoc，也从未保存过任何类型的好文档。（哦，罪过！！：））

我现在需要专注于我业务的非技术方面，并将这个巨人交给编程团队进行维护和新功能。那么，我能做些什么……最有用的注释/文档是什么？追溯性文档的最佳策略是什么？（有这方面的书吗？）

---

另外，感谢您几个月来的帮助。一年前我几乎不懂HTML。你让我经历了这一切

我倾向于像你一样，追溯性地评论，如果我有评论的话。然而，当我这样做的时候，我尝试主要记录我的自定义函数和类，以及代码的重要部分。我注意到如下情况：

所需参数

返回值

功能说明

评论时最好考虑一下，如果你突然消失，无法解释你的代码，会发生什么。接手的开发者需要知道和理解什么。显然，您也不应该使代码过于抽象（即，除非适当，否则只使用变量名，如$x、$y、$z）

70K线并没有那么大。它可能比您通常从事的项目要大，但至少不会太大，以至于一个人无法理解其中的大部分内容。这可能是你第一次遇到麻烦的原因。浏览每个文件并写几句关于这个类所做的事情并不会让你感到痛苦

70K行太大了，无法强加给某人或某个团队，而不解释它的作用和原因。可怜可怜可怜的下属（并减少他们浪费在挠头上的工时），至少要写一张路线图，详细说明项目做什么，如何组织，哪些部分对绩效或满足要求很重要，哪些部分需要工作。如果您对项目有任何书面要求，则应包括这些要求

我可以想象，在您让您的团队处理这堆未经记录的代码之前，您至少计划与团队成员坐下来谈一天，给他们介绍一下情况。写下你想告诉他们的一切。在与团队真正会面之前，给他们一些时间阅读该文档。现在，您可以利用这一天与他们一起通过回答他们的问题来完善文档。确保答案进入下一版本的文件。让您的团队的首要任务是解决您创建的问题。这将有助于他们在开始实施新功能时做好准备

为可预见的未来回答团队提出的问题。创建某种系统来组织和保存您提供的信息。维基看起来很明显，但你也要确保新问题得到注意并迅速得到回答。缺陷跟踪系统可以很好地工作。这样的问答形式也可以

改变你对文档的态度。从错误中吸取教训，改变你的方式，鼓励/坚持人们花时间记录他们所做的事情。通过连接缺陷跟踪系统和版本控制系统，尽量使文档自动化。为您的员工提供制作有用文档所需的资源。让一个人负责文档

---

我只有一条建议。手工操作，并解释代码为什么做它所做的，而不是它所做的。它的作用是显而易见的，但“为什么”不应该被忽视。除非你知道为什么某些事情是以某种方式进行的，否则有些事情可能看起来非常疯狂。如果代码是不言自明的，那么注释就是一个障碍。但是，如果代码做了一些奇怪的事情，您绝对应该在那里使用一些注释。