On Thursday, 19 March 2015 at 22:04:01 UTC, Walter Bright wrote:
On 3/19/2015 2:43 AM, deadalnix wrote:
Here is what will pass review :
Presumably the reviewers will have some common sense and taste.
class User {
/**
* Accessor to get the id of the user.
*
* @return : the id of the user
*/
uint getUserID() { ... }
/**
* Accessor to get the name of the user.
*
* @return : the name of the user
*/
string getName() { ... }
Accessor functions that merely return a field variable are bull
anyway.
That is completely missing the point. If that is not clear enough
:
/**
* This class is the in program represention for a user.
* It contains various user related data, and provides
* various facilities for common user related operations.
*/
class User {
/**
* Accessor to get the id of the user.
*
* @return : the id of the user
*/
uint getUserID() { ... }
/**
* Accessor to get the name of the user.
*
* @return : the name of the user
*/
string getName() { ... }
/**
* This method will subscribe the user to the Subscribable
* passed as argument.
*
* S: The Subscribable the user is going to subsribe to.
*
* @throw CantSubscribeException : In case the subscription
fails,
* an exception is thrown.
*/
void subscribeUserTo(Subsribable S) { ... }
/**
* Send a message to the user. This can be used for
commercial offers
* or general information about the system.
*
* msg: The message you wish to send to the user.
*
* @throw MessageNotSentException : If for some reason, the
message isn't
* sent properly, a MessageNotSentException is sent.
*/
sendMessage(string msg) { ... }
// And so on like forever...
}
Mandatory comment block is how you end up with overbloated code
like this where it is explained to you 3 times in the comment
what the method's name already tells you. And that is only the
begging because starting from this point, overtime, comment
become more and more out of date to ends up looking like an
surrealistic form of humor.
