我即将完成一个马拉松9个月的项目 - 一个具有超过70万行代码的Web应用程序。问题是我很少使用注释，从来没有使用过javadoc，也从来没有保存过任何好的文档。 （哦内疚!! :)）追溯记录+评论的策略
我现在需要把重点放在我的业务的非技术方面，并将这个巨人关闭到维护和新功能的编程团队。那么我该怎么做......写出最有用的评论/文档是什么？追溯文档的最佳策略是什么？ （有没有关于这个问题的书籍？）
PS。感谢您的几个月和几个月的帮助Stack Overflow。一年前我几乎不知道HTML。你让我度过了这一切！
70K行不是那么大。它可能比你通常工作的项目要大，但至少它不是很大，一个人不能理解它的大部分。这可能是你首先遇到麻烦的原因。它不会让你通过每个文件并写几句关于班级的功能。
70K行太大而无法强加于某人或某个团队，而没有对它的作用和原因做出某种解释。至少编写一份路线图，详细解释项目的内容，组织结构，哪些部分对于绩效非常重要，或者如何确定哪些部分是重要的以满足需求，哪些部件需要工作。如果您对该项目有任何书面要求，则应包含这些要求。
我想象一下，在你让团队工作在这个没有记录的代码堆之前，你打算至少坐下来看看团队成员一天，并给他们一个方向。写下你希望在这个方向告诉他们的一切。在你真正与他们见面之前，给团队一些文件和一些时间阅读。现在，您可以利用这一天与他们一起回答他们的问题来完善文档。确保答案将其纳入文档的下一个修订版本。让团队的首要任务是解决您创建的问题。这将帮助他们准备好开始实施新功能。
可以回答团队对可预见未来的问题。创建某种系统来组织和保存您提供的信息。一个维基似乎很明显，但你也想确保新的问题得到注意和迅速回答。缺陷跟踪系统可以很好地工作。所以可能会有某种Q &像SO这样的格式。
改变你对文档的态度。从错误中学习，改变你的方式，并鼓励/坚持花时间记录他们所做事情的人。尝试通过连接缺陷跟踪系统和版本控制系统尽可能自动创建文档。为您的员工提供他们需要的资源以生成有用的文档。让某人负责文档。
我倾向于像你一样做，追溯评论，如果我评论。但是，当我这样做时，我尝试主要记录我的自定义函数&类，以及我的代码的重要部分。我注意到的东西，如：
评论时做的最好的事情的解释是想发生什么了，如果你突然消失并无法解释你的代码。接手的开发人员需要了解和理解什么？显然，你不应该让你的代码太抽象（也就是说，除非适用，否则只能使用变量名称，如$ x，$ y，$ z）。
我有一条也是唯一一条建议。用手做，并解释**为什么**代码做它做的事，而不是*它做了什么。它所做的是显而易见的，但“为什么”不应该是未知数。除非你知道为什么某些事情是以某种方式完成的，否则某些东西可能看起来非常疯狂。 – Charles 2011-03-26 05:23:27
根据需要填写评论。如果代码是自我解释的，那么评论就会受到阻碍。但是，如果代码做了一些奇怪的事情，那么你绝对应该在那里使用一些评论。 – 2011-03-26 05:45:25