记录的策略追溯评论
我即将完成一个为期 9 个月的马拉松项目——一个包含超过 7 万行代码的 Web 应用程序。问题是我几乎不使用注释，从未使用过 javadoc，也从未保存任何类型的良好文档。 （噢，罪恶感！！:)）
我现在需要专注于我业务的非技术方面，并将这个巨人交给编程团队进行维护和新功能。那么我能做什么...最有用的注释/文档是什么？追溯文档的最佳策略是什么？ （有关于这个主题的书吗？）
PS。感谢您几个月来对 Stack Overflow 的帮助。一年前我几乎不懂 HTML。你让我经历了这一切！
I'm just about to finish a marathon 9 month project-- a web app with over 70k lines of code. Problem is I hardly used comments, never used javadoc, and never kept any good documentation of any kind. (oh the guilt!! :) )
I now need to focus on the non-technical aspects of my business and pass this giant off to a programming team for maintenance and new features. So what can I do...what are the most useful comments/documentation to write? What's the best strategy for retroactive documentation? (Are there books on the subject?)
PS. Thanks for your months and months of help Stack Overflow. I barely knew HTML a year ago. You got me through it all!
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（2）
70K 行并不是那么大。它可能比您通常从事的项目要大，但至少不会大到一个人无法理解其中的大部分内容。这可能就是让你首先陷入麻烦的原因。浏览每个文件并写几句话来说明该类的功能并不会让您丧命。
如果没有对它的作用和原因进行某种解释，70K 行太大了，无法强加给某人或某个团队。怜悯你可怜的下属（并减少他们浪费在苦苦思索上的工时），至少写一份路线图，详细解释项目的作用、项目的组织方式、哪些部分对性能或性能很重要。为了满足要求，哪些部分需要工作。如果您对该项目有任何书面要求，则应将其包括在内。
我想，在你让你的团队处理这堆未记录的代码之前，你计划至少与团队成员坐下来一天，给他们一个方向。写下您在培训期间想告诉他们的所有内容。在您真正与团队会面之前，请给团队该文件并一些时间阅读它。现在，您可以利用这一天与他们一起回答他们的问题来完善文档。确保答案包含在文档的下一个版本中。让您的团队的首要任务是解决您造成的问题。这将帮助他们为开始实现新功能做好准备。
在可预见的未来能够回答团队的问题。创建某种系统来组织和保存您提供的信息。 wiki 似乎很明显，但您还希望确保新问题得到注意并快速得到解答。缺陷跟踪系统可以很好地发挥作用。类似 SO 的问答格式也可以。
改变你对文档的态度。从错误中吸取教训，改变自己的方式，并鼓励/坚持人们花时间记录他们所做的事情。通过连接缺陷跟踪系统和版本控制系统，尝试使文档尽可能自动化。为您的员工提供制作有用文档所需的资源。让专人负责文档。
70K lines isn't all that large. It might be larger than projects you typically work on, but at least it's not so large that one person can't understand most of it. That's probably what got you into trouble in the first place. It wouldn't kill you to go through each file and write a few sentences about what the class does.
70K lines is way too large to foist upon someone, or some team, without some sort of explanation of what it does and why. Take pity on your poor underlings (and reduce the man-hours that they'll waste scratching their poor heads) by at least writing a road map that explains in detail what the project does, how it's organized, which parts are important for performance or to meet requirements, which parts need work. If you had any written requirements for the project, those should be included.
I'd imagine that before you make your team work on this undocumented pile of code you plan to at least sit down wit the team members for a day and give them an orientation. Write down everything you'd want to tell them during that orientation. Give the team that document and some time to read it before you really do meet with them. Now you can use that day with them to refine the document by answering their questions. Ensure that the answers make it into the next revision of the document. Let your team's first task be to fix the problem you created. That'll help them get ready for the time when they do start implementing new features.
Be available to answer questions from the team for the forseeable future. Create some sort of system for organizing and preserving the information you provide. A wiki seems obvious, but you also want to make sure that new questions get noticed and answered quickly. A defect tracking system could work well. So could some sort of Q&A format like SO.
Change your attitude toward documentation. Learn from your mistake, change your ways, and encourage/insist on people spending time to document what they do. Try to make documentation as automatic as possible by connecting your defect tracking system and your version control system. Give your people the resources they need to produce useful documentation. Put someone in charge of documentation.
我倾向于像你一样，追溯性地评论，如果我有评论的话。然而，当我这样做时，我尝试主要记录我的自定义函数和函数。类，以及我的代码的重要部分。我会记下以下内容：
注释时最好的做法是想想如果您突然消失并且无法解释您的代码会发生什么。接手的开发商需要了解和理解什么。显然，您也不应该使代码过于抽象（也就是说，除非合适，否则仅使用 $x、$y、$z 等变量名称）。
I tend to do just as you do, retroactively comment, if I comment at all. However, when I do, I try to document mainly my custom functions & classes, and important parts of my code. I note things such as:
The best thing to do when commenting is think about what'd happen if you suddenly disappeared and couldn't explain your code. What would the developer who took over need to know and understand. Obviously, you shouldn't have made your code too abstract either (aka, only using variable names such as $x, $y, $z unless appropriate).