java - javadoc 对算法工作原理的解释应该有多深入？

Question

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

例如，我正在开发一个简单的俄罗斯方 block 游戏，我想解释一下如何旋转 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>
 */

我应该简单地省略分步说明，更喜欢类(class)其余部分的可读性，我应该忽略这个问题，更喜欢读者，还是应该提供指向类似算法的外部资源的链接已经深入解释，可能会导致稍后出现死链接？还是别的？

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 - 但我会保留它，因为复杂性是另一个读者(或 future 的您)想知道的。

为了让审阅者更容易理解您的代码，我建议在实际方法中解释算法中较难的部分，而不是作为 javadoc。有(至少)三个很好的理由:

1. 实际代码到注释的距离更短，您可以将注释分散得更多。

2. IDE 通常使用 JavaDocs 来快速了解方法/类的作用，将代码的完整解释放在 JavaDoc 中违背了这一目的。

3. 可能不适用于您的情况，但最好记住，JavaDocs 通常在发布 API 之类的内容时发布。您不需要发布源代码，但 JavaDocs 几乎总是包含在内，并且通常也发布在 Web 上。如果您的代码中有一个算法可以做一些令人惊奇的事情，而您出于商业目的想要保密，那么它确实会破坏在 JavaDoc 中解释该算法的目的。 ;-)