如何记录必然复杂的代码结构？

如果我的一段代码在数学或结构上相当复杂且不可简化，那么我将如何记录这段代码？特别是，如何确保可能没有我本人的数学或建筑技能的人可以从文档中理解？我也应该记录所有数学吗？链接到教程？在复杂结构的情况下是否进行一些视觉辅助链接？

这实际上取决于代码和数学的复杂程度。代码本身应该（尽可能一如既往）尽可能地自我记录。正确命名变量，实现逻辑简洁的方法（而不是宏功能），在适当的地方（例如，当代码的实际作用不明显时）添加内联文档。

如果您使用的是非显而易见的算法，请添加指向其引用源的链接。这是一种合理的做法，因为它为开发人员提供了一种非常快速的方法来了解您在做什么。就像我说的那样，如果它是一种非显而易见但复杂的算法，则很有用。这应该证明（a）您所做的事情有意义，并且（b）某人已经证明它有效。

一个很好的例子是我围绕模糊文本匹配所做的一些工作。我对算法进行了大量研究，并实现了所谓的“史密斯-沃特曼算法”（实际上用于DNA序列，但通常适用于“匹配”）。因此，我不是简单地实现算法，而是在网上找到参考，并包含一个或两个链接。如上所述，这表明（a）我的算法与已发布的算法匹配，并且（b）该算法已经过审查并证明有效。

但是，这并不一定说明代码如何工作以及各种类应该做什么。当您去写一些“真实的”文档时（系统的开发人员指南），您应该解释自己做了什么，并提供足够的信息以备将来支持。我认为该文档应由技术不可知的人员阅读；它不需要“沉没”，但它应该排除行话，而不要依赖假定的知识。

围绕来源的评论是您应该做的第一件事。这样可以确保直接通过代码直接链接到文档。如果文档非常复杂，请考虑仅在注释中发布摘要，然后再链接到一些外部文档的链接，其中包含有关体系结构/复杂算法的更完整描述。但是，如果不太复杂，可以考虑将所有文档放在一个地方。这将使您的代码/文档保持同步并一起阅读的可能性最大化。

根据您的团队/公司的需要记录代码。如果一个小。开发人员将需要维护代码，您可能需要详细介绍一些数学运算。这是一项管理决定，他们必须给您必要的时间。

我认为您不必过多地编写代码，而不必为一个较小的开发人员所取代。如果这是一个问题，则需要给您时间进行记录。

您无需在网络上搜索它们。