Насколько глубоко должны быть объяснения Javadoc о том, как работают алгоритмы?

Question

Как подробно я должен описать, как работает алгоритм?

Например, я работаю над простой игрой в тетрис и хочу объяснить, как я вращаю тетромино таким образом, что объяснение не охватывает 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 тем, что делает метод, а не тем, как он это делает. Это избавляет вас от обновления ваших JavaDocs каждый раз, когда вы меняете свой код. В вашем случае я был бы рад написать:

/**
 * 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. JavaDocs часто используются в IDE, чтобы получить быстрый обзор того, что делает метод / класс, помещая полное объяснение кода в JavaDoc, и это побеждает.

3. Возможно, это не применимо в вашей ситуации, но, возможно, стоит иметь в виду, что JavaDocs часто публикуются при публикации чего-то вроде API. Вам не нужно публиковать исходный код, но JavaDocs почти всегда включены, а также часто публикуются в Интернете. Если в вашем коде есть алгоритм, который делает что-то удивительное, что вы хотите сохранить в тайне для бизнес-целей, это действительно лишило бы смысла объяснение алгоритма в JavaDoc.;-)