How in depth should I describe how an algorithm works?
For example, I'm working on a simple tetris game, and I want to explain how I rotate the tetrominoes in a way that the explanation doesn't cover a 100 lines, but the reader fully understands what I'm doing.
My javadoc for the algorithm as it is now:
/**
* 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>
*/
Should I simply omit the step-by-step illustration, prefering the readability of the rest of the class, should I ignore this issue, prefering the reader, or should I give a link to an external source where a similar algorithm is already explained in depth, possibly resulting in a dead link later? Or something else?
I suggest limiting the javadoc to what a method does, rather than how it does it. This saves you from updating your JavaDocs every time you change your code. In your case, I'd be happy with writing:
/**
* 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.
*/
You'll have to update your JavaDocs if you improve your algorithm of course - but I'd leave it in as the complexity is something another reader (or future you) would like to know.
For the purpose of making it easy for a reviewer to understand your code I would suggest explaining the more difficult bits of the algorithm in the actual method, rather than as a javadoc. There are (at least) three good reasons for this:
Distance from actual code to comment is shorter, and you can spread the comments out more.
JavaDocs are often used by IDEs to get a quick overview of what a method/class does, putting the whole explanation of the code in the JavaDoc defeats this purpose.