javadoc应该如何深入地解释算法的工作原理？

Question

我应如何深入描述算法的工作原理？

例如，我正在开发一个简单的俄罗斯方块游戏，我想解释一下如何旋转tetrominoes，这样的解释不能覆盖100行，但读者可以完全理解我在做什么。

我的算法的javadoc现在是：

/**
 * Rotates the tetromino 90 degrees clockwise.
 * <p>
 * The rotating algorithm guarantees O(n^2) time complexity and O(1) space
 * complexity, n being the width/height of the tetromino's layout.
 * <p>
 * The algorithm works by rotating each layer of the layout. A layer is
 * rotated by choosing 4 elements, one from each of the layout's sides, and
 * swapping them with each other in a clockwise manner. See an illustration
 * with the I-tetromino below:
 * <p>
 * <pre>
 * Layout:
 * 
 *     . . 1 .
 *     . . 1 .
 *     . . 1 .
 *     . . 1 .
 * 
 * Its first and second layer (layers 0 and 1):
 * 
 *   0:  x x x x   1:  . . . .
 *       x . . x       . x x .
 *       x . . x       . x x .
 *       x x x x       . . . .
 * 
 * First we swap the first layer's elements, 4 at a time:
 * 
 *   layout now:    swap these elements:
 * 
 *   . . 1 .        x . 1 x
 *   . . 1 .        . . 1 .
 *   . . 1 .        . . 1 .
 *   . . 1 .        x . 1 x
 * 
 *   layout now:    swap these elements:
 * 
 *   . . 1 .        . x 1 .
 *   . . 1 .        . . 1 x
 *   . . 1 .        x . 1 .
 *   . . 1 .        . . x .
 * 
 *   layout now:    swap these elements:
 * 
 *   . . 1 .        . . x .
 *   . . 1 .        x . 1 .
 *   1 . 1 .        . . 1 x
 *   . . . .        . x . .
 * 
 * Then we swap the second layer's elements:
 * 
 *   layout now:    swap these elements:
 * 
 *   . . . .        . . . .
 *   . . 1 .        . x x .
 *   1 . 1 1        1 x x 1
 *   . . . .        . . . .
 * 
 *   layout now:
 * 
 *   . . . .
 *   . . . .
 *   1 1 1 1
 *   . . . .
 * 
 * The tetromino is now rotated.
 * </pre>
 */

我应该只是省略分步说明，还是希望该类的其余部分具有可读性，还是应该忽略这个问题，而还是希望它是一个读者，还是应该给一个外部源提供链接，而该外部源中已经解释了类似的算法？深度，以后可能导致死链接？或者是其他东西？

Answer 1

我建议限制的Javadoc以什么样的方法做，而不是如何它它。这使您不必在每次更改代码时都更新JavaDoc。就您而言，我很乐于撰写：

/**
 * Rotates the tetromino 90 degrees clockwise.
 * <p>
 * The rotating algorithm guarantees O(n^2) time complexity and O(1) space
 * complexity, n being the width/height of the tetromino's layout.
 * <p>
 * @param, @return, @throws etc goes here.
 */

当然，如果您要改善算法，就必须更新JavaDocs-但我将其保留下来，因为复杂性是其他读者（或您将来希望）知道的。

为了使审阅者更容易理解您的代码，我建议您在实际方法中而不是作为Javadoc来解释算法中比较困难的部分。至少有三个充分的理由：

1. 实际代码与注释之间的距离更短，并且您可以将注释分布得更多。

2. IDE经常使用JavaDocs来快速概述方法/类的功能，将代码的完整说明放在JavaDoc中会破坏此目的。

3. 也许不适用于您的情况，但可能要牢记的是，发布Java API时通常会发布JavaDoc。您无需发布源代码，但是JavaDocs几乎总是包含在内，并且也经常在网络上发布。如果您的代码中有一种算法可以做一些令人惊奇的事情，并且您想出于商业目的对其保密，那么它实际上会破坏在JavaDoc中解释该算法的目的。;-)