用代码记录数学逻辑

有时，尽管不是经常，但我必须在代码中包含数学逻辑。所使用的概念大多非常简单，但是生成的代码却不是-许多目的不明确的变量，以及某些意图不那么明显的操作。我的意思并不是说代码不可读或不可维护的，只是它的waaaay难度比实际的数学题理解。我尝试评论最难理解的部分，但存在与仅对其进行编码相同的问题- 文本不具有数学的表达能力。

我正在寻找一种更有效且易于理解的方式来解释某些复杂代码（最好是代码本身）背后的逻辑。我考虑过TeX-编写文档并将其与代码分开生成。但是然后我必须学习TeX，并且文档本身也不会包含在代码中。我想到的另一件事是对写在纸/白板上的数学符号，方程式和图表进行拍照，并将其包含在javadoc中。

有没有更简单明了的方法？

PS给变量赋予描述性名称（timeOfFirstEvent而不是t1）实际上会使代码更冗长，甚至更难阅读。

在这种情况下，正确的做法是实现算法，公式或具有与主要真实世界源代码完全相同的变量名的任何变量（只要编程语言允许这样做），并在上面加上简洁的注释类似于“ [Knuth1968]中描述的Levenshtein距离计算”，其中的引用链接到易于访问的数学描述。

（如果不具备这样的提法，但你的数学是可靠的和有用，也许你应该考虑自己的作品发表，只是在说）。

当我不得不实现这样的算法时，我要做几件事。

1. 尽可能将算法隔离到自己的方法或最好是类中。我当前的项目有自己的等效Math类，可以向其中添加复杂的算法。

2. 提供有关该算法应如何进行的概括的摘要，包括任何常用的缩写词或对该术语的简称。我在方法本身中执行此操作，因此它与代码一起存在。

3. 用技术/数学术语提供该算法的摘要，并包括我所知道的所有外部参考。同样，我使用方法本身来执行此操作，因此它更有可能保持相关性。在这种情况下，纯文本不是很好，因此我将尽我所能引用数学术语，并在其旁边的括号中加以澄清。例如， x^y (x raised to the power y)

4. 记录下我如何将算法分解为各个部分，并指出每个变量在算法中代表什么。例如。t1 is time of first event

5. 编写算法代码并注释复杂的部分。本质上，我将在算法本身不明显或不直观的任何步骤中添加注释。我特别确保我评论所有非显而易见的快捷方式，以及为什么我可以在实现中使用它们。

6. 编写一些单元测试，以验证算法的运行。

最后，如果它真的真的非常复杂，那么我会拒绝接受这样一个事实，即我在该项目的剩余时间内都拥有该代码。

我不喜欢依靠外部文档来让其他人理解代码。是的，有时可能有必要，尤其是当进入神秘的细节时。但是，只要有可能，我都会尝试将所有内容保留在代码本身内，以便它有机会保持更新并易于定位。在这种情况下，我重视文档表达能力上的信息可访问性。

在围绕量化金融经济学研究的项目中，我们利用了大量数学，并结合了已经发表的内容：

1. 提供指向您正在使用的主要来源的链接。对我们来说，最简单的方法是使用BibTex句柄，该句柄基本上是可以让所有相关人员查找的论文的ID。根据具体的来源，我们也定期添加方程式参考。

2. 提供所有变量的说明。同样，如果原始论文使用希腊字母或其他字母，则使用Tex。原因是经常有足够的论文和书籍使用不同的符号。如果有人需要重做数学运算，这将使计算变得容易得多。

3. 尝试将方程式编码为一件。这种方式容易识别得多。请勿将完整方程式的Tex-Code张贴到代码中-方程式很短，并且tex混乱且多余，或者方程式庞大，并且tex代码无用，除非您对其进行编译（使用a而是参考）。将方程分解成小块很难知道发生了什么（至少如果您精通数学）。

恕我直言，最重要的认识是公式通常取决于上下文。我知道的每一篇数学论文都花时间来建立模型的环境。您应该做同样的事情。

文字没有数学的表达能力

你是对的。由于您已经在寻找一种在代码之外进行编码的方法，而且Tex除了学习难度大之外，还算是过高的选择，我的建议如下：

使用OpenOffice.org/LibreOffice Math Equation Editor。

免费。它是开放的。

您可以直观地使用它，也可以用特殊语言编写方程式。

您不必立即学习该语言，因为当您使用GUI时，将在面板中生成“代码”，以供您查看。

在上面板中，您可以使用调色板“绘制”方程式。在下面的面板中，生成等效的符号。掌握了表示法之后，您可以以另一种方式进行操作，在下部面板中编写表示法，在上部面板中查看图形输出。