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);
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.