如何记录代码库中的陷阱和陷阱？

Question

在与开发人员一起使用代码库时，有哪些方法可以记录陷阱和问题呢？我正在与一组开发人员合作开发一个大型代码库，并且有许多小事情会在代码、配置和测试中造成头痛和挫折。将它们放入github页面似乎不合适，因为它们可能分散在存储库和项目中--所以我的问题是，记录陷阱和常见问题的例子是什么？

Answer 1

易于解释的怪癖和黑客行为可以用一种评论的形式加以解释。毕竟，这些评论的目的恰恰是--当一个人不能或没有足够的资源使不清楚的代码更清晰的时候，来拯救它。这里的目标是帮助正在阅读给定代码行(或一系列代码)的程序员，并问自己，过去发生了什么错误，导致了这段特定的代码。

奇怪的架构决策(当它们被做出时看起来是正确的，然后看起来是错误的，但是没有人努力重构代码基)应该被记录在架构文档中。把它放在一个任何从事这个项目的人都能很容易找到它的地方，并确保加入这个项目的新程序员一定会阅读它。

在这两种情况下，请确保您(和您的同事)都明白，有一个充满缺陷和问题的源代码是不正常的，需要进行记录。

与您的产品所有者交谈，每周预留几个小时或几天用于大型重构任务(即设计或架构级别的更改)。如果你不这样做，这个项目就注定要失败，就像其他每一个技术债务不断增加的项目一样。

此外，代码级重构应该是您的常客活动:每当您处理一段代码时，请确保您遵循童子军规则：“留下代码比找到代码更好。”如果某个方法不清楚，因为有人为变量使用了一个字母的名称，请不要保持这种方式:重命名它们。它不需要很长时间，而且它将支付下一次，当某人不会损失十分钟，试图弄清楚这个方法如何工作。大多数重构技术都是非常简单和快速的实现，而且很多都非常有效。

Answer 2

没有怪癖会更好

首先，最小惊讶原则适用于：

从1984年起，这一原则的一个典型表述是：“如果一个必要的特征具有很高的惊讶因素，可能需要重新设计该特性。”

换句话说:消除怪癖。您的开发人员在处理怪癖方面损失的时间可能比完全消除怪癖所需的时间要大。

XKCD提供了一个非常方便的指南，可以根据遇到的频率向您展示您可以花费多长时间来修复某件事情的粗略数字：

举个简单的例子，如果你的团队每周遇到一次特殊的怪癖(平均)，你会花费30分钟(平均)，而这个产品预计在接下来的5年里会使用，这会给你21小时的时间，或者在你花比你节省的时间更长的时间之前，用不到3天的时间来修复这个怪癖。即使你每月都会遇到同样的问题，这也会给你一天的时间来解决它。

注意，花在怪癖上的时间很快就加起来了。错误修复，重新运行一个全面的测试播放列表，在每天站立期间的沟通，合并冲突，培训，阅读文档的怪癖，.还要注意的是，训练需要双倍的时间，因为这是培训师和学员双方的时间投资。

文档不是万灵药

不要误解我的意思，文档是必不可少的，特别是当您对母线因数进行解释时，但是文档不应该是您唯一的防线。

每当他们遇到问题时，在咨询其他人之前，没有人会阅读整个文档(也不应该)。如果他们认为这个问题是新的，他们就会花时间去研究这个问题，这需要时间(怪癖本身就是违反直觉的)。如果他们不认为这个问题是新的，他们会问一个更有经验的人，如果有一个已知的解决方案。

文档对于参考是很好的，但它并不能从本质上防止开发人员通过询问问题来分散彼此的注意力。当开发人员分心时，他们的生产力会下降。，而分心的持续时间在这里是一个令人惊讶的可忽略的因素(不管分心需要几秒钟、几分钟还是几个小时)。

无干扰进入区域的另一种方法是避免所有分心。有些人比其他人对分心更敏感，但我们应该始终致力于最大限度地减少那些把我们的注意力从我们目前正在做的事情中拉出来的事情。避免上下文切换成本是一项巨大的胜利。

文章的其余部分在这里不太相关，但它涉及到如果您想要保持生产率的话，不切换上下文的重要性。

当您需要记录

时，

但是有时候，怪癖太根深蒂固了，或者你无法说服管理层重构代码。这些事情都会发生。当他们这样做的时候，文档是你至少能做的(愤世嫉俗的双关语)。

对于一次性的怪癖(即位于单行或文件上)，内联注释是最容易被注意到的警告。这确保了查看古怪代码的开发人员立即被提醒注意到这种怪癖。

如果这些怪癖在体系结构中很流行，因此分布在整个层(或更糟的是多个层)，则内联注释不会减少它。你不想在你的代码库上乱涂。

在这里，更合适的做法是为该项目制定一个开发人员指南，其中概述常见的缺陷(除其他外)。阿瑟的回答称这是一份“建筑文件”，但要点是一样的。

作为一名顾问，我倾向于为无法协助开发或持续不断地审查代码的项目编写这些指南(无论是有限的合同期限还是其他责任)。该文档包含的不仅仅是陷阱，但内容的总体目的是引导开发人员在实现、多层职责分离、依赖关系以及上述的怪癖、陷阱和常见问题方面朝着正确的方向前进。

这看起来可能有点过火，但在我的工作环境中，我经常为一些团队编写这些文章，因为这些团队的常规做法是糟糕的，或者是那些在一致性和/或良好实践指导方针上苦苦挣扎的团队。考虑到“有许多小事情会导致代码、配置和测试中的头痛和挫折”，如果不能持续依赖经验更丰富的开发人员/审查员的指导来避免这种怪癖，那么这种情况并不是非常不同的，而且类似的文档可能也是有必要的。