Насколько глубоко должны быть объяснения Javadoc о том, как работают алгоритмы?
Как подробно я должен описать, как работает алгоритм?
Например, я работаю над простой игрой в тетрис и хочу объяснить, как я вращаю тетромино таким образом, что объяснение не охватывает 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>
*/
Должен ли я просто пропустить пошаговую иллюстрацию, предпочитая удобочитаемость остальной части класса, должен ли я игнорировать эту проблему, предпочитая читателя, или я должен дать ссылку на внешний источник, где подобный алгоритм уже объяснен в глубина, возможно, приведет к мертвой ссылке позже? Или что-то другое?
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. Для этого есть (как минимум) три веские причины:
Расстояние от реального кода до комментария короче, и вы можете распространять комментарии больше.
JavaDocs часто используются в IDE, чтобы получить быстрый обзор того, что делает метод / класс, помещая полное объяснение кода в JavaDoc, и это побеждает.
- Возможно, это не применимо в вашей ситуации, но, возможно, стоит иметь в виду, что JavaDocs часто публикуются при публикации чего-то вроде API. Вам не нужно публиковать исходный код, но JavaDocs почти всегда включены, а также часто публикуются в Интернете. Если в вашем коде есть алгоритм, который делает что-то удивительное, что вы хотите сохранить в тайне для бизнес-целей, это действительно лишило бы смысла объяснение алгоритма в JavaDoc.;-)