Question

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

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

我现在算法的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。至少有三个很好的理由：

从实际代码到评论的距离更短，您可以更多地传播评论。
IDE经常使用JavaDocs来快速了解方法/类的作用，将JavaDoc中代码的完整解释置于此目的。
也许不适用于您的情况，但也许可以记住，JavaDocs经常在发布类似API时发布。您无需发布源代码，但JavaDocs几乎总是包含在内，并且通常也会在Web上发布。如果您的代码中有一个算法可以做出令人惊奇的事情，那么您希望为业务目的保密，那么它将无法解释在JavaDoc中解释算法的目的。 ; - ）

如何深入地解释算法如何工作？

1 个答案: