On 3/19/15 3:26 PM, deadalnix wrote:
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.
I agree with the uselessly overcommented code you describe; I've seen
plenty of it too.
And yet there is a little room for useful comments here: does getName
return the user's given/family name or an account username? Possibly
obviated by the context of whatever app this User class is in, but how
will the user receive the sent message? Comments on purpose and use can
save a bit of maintenance developers' time.
