如何向同事介绍代码

您如何将代码库引入团队中的新成员，该代码库可能相当复杂并且与很多“陷阱”缠在一起？

我认为最简单的方法是用图表来布局整个体系结构，并在新人逐渐习惯于代码后花几个星期（或几个月）来赋予新定义的任务（范围广）。

但是，作为顾问（和初级员工），由于时间限制或团队角色指定，我不能总是这样。（我在这个特定项目上的工作时间是其他人的两倍，因此“初级”绝不是“对代码/项目的了解较少”。）

我现在已经受了好几次任务，向项目和代码介绍一个新成员，可悲的是，每次我发现自己的能力都不比以前更好。我喜欢图表和图片，但是经常觉得它们并不能充分说明系统的复杂性。（小孩子的“陷阱”呢？）

该项目已经到了将要交付给客户的地步，为了使事情更具挑战性，我将要与之进行知识转移的人实际上只是大学毕业。（并不是说我与高级开发人员进行知识转移时会更好。）

我每个月参加一次用户组，并在出现其他机会时参加，因此我没有被无用的新主题介绍，但是感到我复制有效知识共享的能力严重不足。

任何建议将不胜感激。我主要是在寻找可以遵循的指南。例如：您从哪里开始？你如何进行？您如何在不花大量时间的情况下涵盖听众不熟悉的技术或模式？您在哪里将业务逻辑与代码结构联系在一起？

谢谢！

（与往常一样，请根据需要随意编辑问题。）

第一步当然是从代码中删除“陷阱”。清晰，简洁，一致的代码更易于进入，使用和调试。

你从哪里开始？

我问新手，他们想如何进入代码库。每个人的学习方式都不一样。有些人喜欢没有什么工作要做。有些喜欢调试现有代码。有些人希望查看代码运行以了解其功能。有些人想从入口点开始，然后四处浏览。有些人想要visio图表...没有固定的模式对每个人都效果最佳。

您如何在不花大量时间的情况下涵盖听众不熟悉的技术或模式？

我避免了。让它们成为黑匣子，直到新来者询问它们。然后提供足够的信息来掌握这些知识，并暗示他们可以在自己的时间上学习更多，或者稍后询问一般知识何时变得更加众所周知。

您在哪里将业务逻辑与代码结构联系在一起？

我尽量不要。对于新来的人来说，独立学习通常总是更好的选择，这样它就可以以一种更自然的思维方式摆在他们的脑海中。

要记住的一件事是使指令简短。人们往往会很快结帐，因此此时的任何更多指示都不会“坚持”下去。向他们展示15-60分钟（不同人的注意力跨度不同），然后让他们休息5-30分钟以进行处理。

以我的经验，弥合体系结构图所提供的广泛概述与实际使用代码的详细细节之间的鸿沟的一种好方法是对系统进行深入研究，例如，在请求到达时发生的情况（对于服务器代码） ）或用户输入（用于客户代码），然后逐步说明涉及的所有代码层。

另一种方法是源代码的“导览”，即遍历程序包/名称空间/模块/目录，并解释它们中的每个代码总体上的功能。当然，这需要在逻辑上布置代码。

你不是教他们的代码库，你教他们的工作。不要试图去思考他们可能需要什么，而要看看您在工作时实际需要知道的内容。

总结过去几个月的错误跟踪历史，scrum用户故事，状态报告和源代码控制提交。您最接触过哪些文件？什么代码最有问题？最长的任务是什么？如果您在过去几个月中没有碰过它，它的重要性可能不如您想象的那么重要。

查看您桌上的打印输出。检查您最近的浏览器历史记录。查找您经常引用的已保存电子邮件，您使用的联系人以及您下载的文档。我传递给其他人的一些最有用的参考资料是我在初次学习或设计系统时为自己保留的注释。哪种参考资料对您最有用？

接下来拉起您的已知积压。您需要研究什么才能完成这些任务？哪些代码区域最有可能包含该问题？传达信息时，就像您自己记笔记一样。

如果您在日常工作中参考图表或图表，则将其包括在内。如果您从来没有打扰过一个人，那么对您的继任者/同事来说也可能不会那么有用。

教学时最困难的任务之一就是试图让自己陷入困境。在这种情况下，您正处于他们的立场。充分利用它。

支持工作是最好的，轻松解决问题，并引导他们遍历可发现的区域。他们将快速学习代码如何组合在一起。当然，他们会来询问有关此错误和代码库的问题，但是他们会到达那里（并且您会修复一个错误）。通常，通过示例更容易解决问题，类似地，通过在调试器中运行代码库来制定代码库也更容易。

如果您不确定代码更改（或者通常情况是不确定的，除非我熟悉代码库，否则我通常无法确定自己的代码修补程序），然后可以在签入之前进行检查。

当然，您现有的广泛概述和框图思想是必不可少的第一步。