将自己的项目传递给别人 - 该怎么办？ [关闭]

Question

通常情况下，项目会传递给其他人。 通常这个过程对双方来说都是不愉快的 - 新主人抱怨可怕的文档，错误和糟糕的设计。 然后，原来的所有者因为项目问题，修复旧错误的请求等问题困扰了几个月。

我可能很快就会将我的一个项目提供给其他人，这样我就可以专注于我的其他项目。 我想知道我该怎么做才能使这种转移尽可能顺利。 我已经拥有的是一个体面的文档，代码是相当好的评论，我仍然在改进它。 它是一个中等规模的项目，不是很大但仍然不是你可以在一周内编码的东西。

我正在寻找一系列应该做的事情，以帮助未来的所有者接管项目，同时将为我提供所有那些烦人的问题，例如“这个功能做了什么，这个课程的目的是什么有...”。 我知道文档是必须的 - 还有什么？

注意：虽然我的项目是用C ++编写的，但我相信这是一个与语言无关的问题。 如果您认为某些语言特定的内容，请同时提及。

Answer 1

文档是一回事，让它成为另一个新项目所有者的负责人。 恕我直言，这是一个典型的情况，“少即是多” - 你的同事为理解某事而阅读的文件越少越好。 而且，当然，学习需要时间 - 对你们两个人来说，接受它。

所以

• 而不是编写大量文档，使您的代码自我评论

• 将所有文档/源代码等放在一个干净且命名良好的文件夹结构中

• 确保您的构建过程几乎完全自动化

• 不要忘记记录您的部署过程，如果它不是自动的

• 清理，清理清理！

Answer 2

在接管项目时，文档当然是可取的，但更重要的是一个好的测试套件。 试图修改一个你无法测试正确性的程序是一场噩梦。

Answer 3

文档，但在所有级别：

• API文档
• 高级架构：存在哪些组件，它们的关系和依赖关系是什么
• 对于每个组件，指向重要代码段的高级描述
• 教程：如果你想做X，这是怎么做的
• 数据：它使用什么数据以及如何使用数据库模式
• 习语：如果你在代码中创建了一些习语，请解释它们

并且，首先，让这个人亲自介绍上述所有内容，希望在一对编程方式中做一些必要的改变

Answer 4

新主人抱怨可怕的文档，错误和糟糕的设计。

我怀疑无论你做什么，新主人总会抱怨什么。 人们是不同的，所以看起来容易理解的东西对于其他人来说看起来很恐怖而且非常复杂。

然后，原来的所有者因为项目问题，修复旧错误的请求等问题困扰了几个月。

在这种情况下，你应该明确拒绝提供帮助。 如果你不拒绝，你可能最终会免费做别人的工作。 如果维护项目不再是你的工作，那么新人应该在没有你帮助的情况下解决他的问题。 如果“新人”无法处理，他不适合这份工作，应该退出。

这是一个中等规模的项目，

“中等大小”相比什么？ 多少行或代码，多少个文件，多少兆字节的代码？

我想知道我该怎么做才能使这种转移尽可能顺利。 我已经拥有的是一个体面的文档，代码是相当好的评论，我仍然在改进它。

我会像这样处理它：

1. 首先，扫描整个代码并执行：
   1.1删除所有已注释掉的代码块。
   1.2删除所有未使用的例程和类（我说的是“被遗忘”的例程，而不是实用程序库的一部分）。
   1.3确保所有代码遵循一致的格式规则。 即你不应该在同一个应用程序中混合class_a ， ClassA和CClassA ，你不应该使用不同的样式来放置括号等。
   1.4确保所有名称（类，变量，函数）都不言自明。 您的代码应尽可能自我解释 - 这将使您免于编写太多文档。
   1.5在有复杂或难以理解的功能的情况下，写评论。 保持它们尽可能短，只有当它们绝对必要时才发布。
   1.6尽量确保没有遗留的已知错误。 如果存在已知错误，请记录它们及其行为。
   1.7从项目目录中删除垃圾（项目中未使用的文件等）
   1.8如果可能，请确保代码仍然编译并按预期工作。
2. 使用doxygen生成html文档。 重复几次，修改代码注释直到你满意为止。 或者直到你对结果有点满意为止。 不要跳过此步骤。
3. 如果有一个包含整个开发历史的版本控制存储库（比如git存储库），请将其交给新的维护者，或者给他（她？）一个存储库的功能副本。 这对于（git）二等分和查找错误来源非常有用。

一旦完成，代码转移到新的维护者，不要提供“免费帮助”，除非你得到报酬（或除非你得到其他帮助，或除非是你的老板的订单，这使得帮助新维护者是你当前任务的一部分）。 维护代码不再是你的工作，如果新的维护者无法处理它，他就没有资格胜任这项工作。

Answer 5

我认为只需要两个简单的规则就可以避免大多数问题。

1. 保持代码与平台样式指南一致。
2. 命名，命名和命名。

如果项目很大，那么你只需要与新人一起运行一些代码阵营。 这个没有捷径。

还要记住抱怨的发生主要是因为新人没有足够的资格，即不理解某事。 这就是为什么保持简单是很重要的。 如果他更有资格，那么我猜你应该得到它;）

一些好的建议从哪里开始黑客/改变事物总是比文档更好。 熟悉代码后，请将文档视为备份材料，它绝不应该是起点（除非您是具有无限资源和时间的特殊技术作家）

Answer 6

如果你说的话有好的文档和评论代码，那么你已经完成了自己的工作。 只需确保文档包含高级文档（体系结构，数据流等）以及较低的模块或过程级文档。

如果这种情况可以，我强烈建议您使用某种类型的合同来保护自己，该合同规定了您将提供的未来支持（如果有）以及持续时间。

Answer 7

我认为对于这样的情况，最重要的是一个工作的，完整的构建，自动编译，记录和测试项目。 这样，新开发人员可以使用它定义明确的点。 然后，他可以从测试和文档中找出原文。