记录和移交源代码

Question

我最近离开了我以前的学生工作，作为一名兼职开发在小型ERP管理公司。

在公司工作期间，我开发了几个模块，以便与ERP系统集成。此外，我还开发了一个应用程序，并为上述应用程序开发了后端。

我被要求记录我的代码库的复杂部分，以便其他开发人员能够进行进一步的开发。

在移交源代码方面有什么最佳做法吗?我应该如何编写文档?我应该在多大程度上编写文档？

作为最后一个注意事项，除了注释之外，我没有对代码进行任何测试，也没有编写任何文档来帮助导航代码结构。产品负责人根本不想让我花时间在这些活动上。

任何输入都是非常感谢的！

Answer 1

据我所知，这个问题有三个方面。

当你还是学生的时候，你是一家公司的兼职开发者。在工作过程中，产品经理不希望您花费时间在测试和文档上。

光是这一点，对产品的成功来说是一个巨大的风险。

一些级别的文档是很重要的，因为很多原因，从入职的新团队成员到帮助现有的团队成员了解他们过去做了什么，以及他们为什么这么做。文档的级别和细节取决于各种因素，例如正在设计和开发的系统的复杂性、组织的大小和结构、遵从性要求等等。

忽略测试，这也可能是一种文档形式，对产品质量有巨大的风险。编写自动化测试不仅捕获了系统当前在不同抽象级别上的预期行为，而且随着设计的改变，如果代码更改导致行为更改，则失败的测试将引发标志。这将迫使开发人员考虑更改，并确保它是适当的，同时，通过编写良好的测试，强调更改的范围和影响。

既然你是一名学生，而不是全职员工，我不认为你能在这个要求上做出太大的让步。但是，如果文档被忽略了，我将确保将其作为未来的风险，并确保文档化和跟踪。如何做到这一点因团队和组织而异。

在某种程度上，你已经离开了这个职位，不再受雇于这个组织，但是他们要求你去工作。

这种情况属于在工作场所和职业生涯中导航的领域，这比软件工程更适合工作场所。然而，我建议你永远不要免费工作。正如我前面提到的，该组织通过推迟文档来冒风险。而不是仅仅推迟到一个合理的点，他们把它推迟到你的工作之外。我反对免费工作，所以我要说，你不再有义务支持以前的雇主，并找到外交方法来避免这一工作，让组织承担与他们的决定相关的费用。

现在，您正在寻找关于文档化您负责构建的软件的良好实践。

我建议阅读Martin关于UML模式的文章，特别是UML作为备注和UML作为素描。这不仅适用于UML，而且适用于任何标准化的建模语言。一般的想法是，仅仅因为一种正式的建模语言为您提供了大量的工具，并不意味着您需要使用所有这些工具。您可以正确地使用核心语言，以获得公认的和通常被理解的符号的优势，但在适合您的受众的不同抽象和细节级别上。

接下来，我将研究各种建模符号，从标准流程图符号到UML和SysML，到C4模型到IDEF。这些符号都有与它们相关的文档。它的优点是，您可以找到一种合适的图表类型，按名称调用它，也许还可以为不懂建模语言的人提供一个链接或参考，说明如何读取它。这节省了您定义语言和交流软件设计的时间，还节省了用于记录软件设计的设计语言的时间。此外，您不仅限于图形符号-文本和表格也有很长的路要走。

最后，我将看看敏捷建模的技术。这是一组原则和技术，用于将软件设计文档的创建与精益和敏捷的价值观和原则结合起来。有一些技术可以平衡创建工作软件和创建适当和有用的文档。

Answer 2

这是最低限度的，虽然是专业的，努力。自动列出所有类/组件。一种“完全性”

然后创建一个结构化的富文本文档，将所有内容都包含在上下文中，什么是控制器，什么是实体类，以及它们是如何一起使用的。

也许也是个术语表。

在最高级的工具，建筑。

菜单，截图和其他你仍然可以/想收集的东西。

这样，未来的开发人员就可以在软件中找到适合自己的方法。