That sort of thing has an obvious problem. Take a fairly simple class:
class Shape
{
public:
void SetAbsolutePosition(uint x, uint y, LengthUnit units = LengthUnit::PIXELS);
void SetRelativePosition(int x, int y, LengthUnit units = LengthUnit::PIXELS);
void SetXAbsolutePosition(uint x, LengthUnit units = LengthUnit::PIXELS);
void SetYAbsolutePosition(uint y, LengthUnit units = LengthUnit::PIXELS);
void SetXRelativePosition(int x, LengthUnit units = LengthUnit::PIXELS);
void SetYRelativePosition(int y, LengthUnit units = LengthUnit::PIXELS);
void SetSize(uint height, uint width, LengthUnit units = LengthUnit::PIXELS);
void SetHeight(uint height, LengthUnit units = LengthUnit::PIXELS);
void SetWidth(uint width, LengthUnit units = LengthUnit::PIXELS);
void SetColor(Color color);
};
What the methods do is bleeding obvious and the whole thing fits on a single screen where you can look at it. Now let's put all those comments in, what are they going to look like typically when inserting them is mandatory?
class Shape
{
public:
/**
* SetAbsolutePosition sets the Shape absolute position
*
* @param x The absolute X coordinate
* @param y The absolute Y coordinate
* @param units The units of the coordinates
* @returns Void
*/
void SetAbsolutePosition(uint x, uint y, LengthUnit units = LengthUnit::PIXELS);
/**
* SetRelativePosition sets the Shape relative position
*
* @param x The relative X coordinate
* @param y The relative Y coordinate
* @param units The units of the coordinates
* @returns Void
*/
void SetRelativePosition(int x, int y, LengthUnit units = LengthUnit::PIXELS);
/**
* SetAbsoluteXPosition sets the Shape absolute X position
*
* @param x The X coordinate
* @param units The units of the coordinate
* @returns Void
*/
void SetXAbsolutePosition(uint x, LengthUnit units = LengthUnit::PIXELS);
/**
* SetAbsoluteYPosition sets the Shape absolute Y position
*
* @param y The Y coordinate
* @param units The units of the coordinate
* @returns Void
*/
void SetYAbsolutePosition(uint y, LengthUnit units = LengthUnit::PIXELS);
/**
* SetXRelativePosition sets the Shape relative X position
*
* @param x The relative X coordinate
* @param units The units of the coordinate
* @returns Void
*/
void SetXRelativePosition(int x, LengthUnit units = LengthUnit::PIXELS);
/**
* SetYRelativePosition sets the Shape relative Y position
*
* @param x The relative Y coordinate
* @param units The units of the coordinate
* @returns Void
*/
void SetYRelativePosition(int y, LengthUnit units = LengthUnit::PIXELS);
/**
* SetSize sets the width and height of the Shape
*
* @param height The length of the height
* @param width The length of the width
* @param units The units of the lengths
* @returns Void
*/
void SetSize(uint height, uint width, LengthUnit units = LengthUnit::PIXELS);
/**
* SetHeight sets the height of the Shape
*
* @param height The length of the height
* @param units The units of the length
* @returns Void
*/
void SetHeight(uint height, LengthUnit units = LengthUnit::PIXELS);
/**
* SetWidth sets the width of the Shape
*
* @param width The length of the width
* @param units The units of the length
* @returns Void
*/
void SetWidth(uint width, LengthUnit units = LengthUnit::PIXELS);
/**
* SetColor sets the color of the Shape
*
* @param color The color to be set
* @returns Void
*/
void SetColor(Color color);
};
So now the class is eight times as long and you have to scroll eight times as much to find anything, in exchange for which you get a bunch of comments that tell you things you already know. Meanwhile writing those comments involved a lot of copy and paste and then changing one or two variable names and descriptions, which violates DRY and is the recipe for erroneous comments.
The better alternative is to comment only those things where the comment provides useful information, so that when you see a comment it strikes you as something you should pay attention to rather than some boilerplate to be ignored because 85% of them are mandatory but useless.
While I understand the argument behind not commenting getters and setters, and it is quite valid, no it is not obvious what each of those methods do. For instance, what is the relative position relative to? Is the colour for the outline of the shape or the fill? Why do you have a width and height for a shape - does that mean it is a rectangle?
But of course I meant my earlier comment particularly for quite complex methods that had very ambiguous behaviour unless defined in a comment that could act as a contract. The contract can then be enforced by writing tests against it, and you know your code works when the tests pass.
It's very common to write the code first, write the tests against the code, and then write a comment against the code if you are lucky, but that doesn't actually prove anything, as the tests will be testing the implementation details, not the contract.
> But of course I meant my earlier comment particularly for quite complex methods that had very ambiguous behaviour unless defined in a comment that could act as a contract.
Which is kind of the point. You do need some kind of documentation for nontrivial methods. But requiring boilerplate documentation for everything encourages the opposite of that because it becomes "fill in the fields" rather than "say something useful." I mean let's say you're right and SetRelativePosition isn't clear about what it's relative to. Which of these is better?
/**
* SetRelativePosition sets the Shape relative position
*
* @param x The relative X coordinate
* @param y The relative Y coordinate
* @param units The units of the coordinates
* @returns Void
*/
void SetRelativePosition(int x, int y, LengthUnit units = LengthUnit::PIXELS);
-or-
/* SetRelativePosition: sets position relative to current position */
void SetRelativePosition(int x, int y, LengthUnit units = LengthUnit::PIXELS);
Unfortunately we all know that, but according to Lake Wobegon management style, not only are all our devs above average and all our code is error free, but also all our information is useful. All of it. Says so right there, on the motivational poster.
It doesn't apply to your example, but sometimes in maint mode the best part about boilerplate comments is being able to search for a synonym that appears in the prose comments but not in the code. In your example you could have some kind of distance calculating function that somehow neglects to mention Pythagorean theorem in the code itself, but very optimistically it would appear in the boilerplate, so I could grep for it.
I'm not sure about Javadoc, but with Doxygen you do not need to put inline documentation immediately next to the code you are documenting. You could put all the documentation at the top of the file and the function declarations at the bottom. This makes it a little harder to maintain the docs while you maintain the code, but it does resolve one of your pain points.
The better alternative is to comment only those things where the comment provides useful information, so that when you see a comment it strikes you as something you should pay attention to rather than some boilerplate to be ignored because 85% of them are mandatory but useless.