On 3/19/2015 2:40 AM, deadalnix wrote:
> And I'm sorry, but if most function require DDoc, your code probably sucks quite
> badly and some renaming should be considered.

I've never seen any code that self-documented "why".

On Thu, Mar 19, 2015 at 3:03 PM, Walter Bright via Digitalmars-d < digitalmars-d@puremagic.com> wrote:
>
>
> Accessor functions that merely return a field variable are bull anyway.
>

I would recommend against opening up this debate.  Suffice it to say that this is a well established pattern that many people use; there is well-trod ground arguing both sides.


>     int foo;
>     int getFoo() { return foo; }
>

A valid reason for doing things like this is future-proof encapsulation. You can change the internal foo to be something entirely different, and the external api never changes (assuming 'foo' is private).


As for the documentation - yeah, don't write docs that duplicate what is there in the method signature.  In the above example, documentation should explain what foo actually is, and why you might need it.  Otherwise is just duplicate boilerplate that should be generated by the doc generator.

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.

On Thursday, 19 March 2015 at 22:05:51 UTC, Walter Bright wrote:
> On 3/19/2015 2:40 AM, deadalnix wrote:
>> And I'm sorry, but if most function require DDoc, your code probably sucks quite
>> badly and some renaming should be considered.
>
> I've never seen any code that self-documented "why".

Indeed, that is why comment are useful. If all your method
require a why, you probably should consider refactoring instead
of adding comments all over the place.

On Thursday, 19 March 2015 at 22:14:02 UTC, Jeremy Powers wrote:
> As for the documentation - yeah, don't write docs that duplicate what is
> there in the method signature.

I'm not a big fan of that. It's one of those slippery slope things. The documentation should be written for a new D user, but the person that writes the method has a very different view of what constitutes duplication. There's too much of that attitude in the existing documentation. If it really is duplication, that should be a decision made by someone else, preferably someone that doesn't know much about the library.

On Thursday, 19 March 2015 at 23:45:03 UTC, bachmeier wrote:
> On Thursday, 19 March 2015 at 22:14:02 UTC, Jeremy Powers wrote:
>> As for the documentation - yeah, don't write docs that duplicate what is
>> there in the method signature.
>
> I'm not a big fan of that. It's one of those slippery slope things. The documentation should be written for a new D user, but the person that writes the method has a very different view of what constitutes duplication. There's too much of that attitude in the existing documentation. If it really is duplication, that should be a decision made by someone else, preferably someone that doesn't know much about the library.

Ok let's be clear. This kind of overpedantic commenting is a good thing in a public, widespread API, like phobos's. Especially since you can generate documentation from it, this is going to be googled for.

That is very bad idea in the general case.

On Thursday, March 19, 2015 22:27:33 deadalnix via Digitalmars-d wrote:
> On Thursday, 19 March 2015 at 22:05:51 UTC, Walter Bright wrote:
> > On 3/19/2015 2:40 AM, deadalnix wrote:
> >> And I'm sorry, but if most function require DDoc, your code
> >> probably sucks quite
> >> badly and some renaming should be considered.
> >
> > I've never seen any code that self-documented "why".
>
> Indeed, that is why comment are useful. If all your method require a why, you probably should consider refactoring instead of adding comments all over the place.

There are plenty of functions that require documentation - especially when they're more powerful. This is especially true when talking about free functions rather than member functions. And having documentation for stuff like what exceptions a function throws can be quite valuable even if the function's primary functionality doesn't need much explanation. I think that it's safe to say that most functions need at least minimal documentation. However, I completely agree that there are a number of functions (especially property functions and other types of simple accessors) which don't need a detailed explanation, and having both a main comment on them and a return and/or param comment on them is redundant and just noise.

So, I fully expect that requiring a return comment or a comment per param will quickly result in documentation comments being overly verbose. That being said, most functions do need some sort of documentation, and there are definitely some functions that will need both the return and param comments (especially the sort of stuff that goes in std.algorithm).

- Jonathan M Davis

On Thursday, 19 March 2015 at 22:14:02 UTC, Jeremy Powers wrote:
>>     int foo;
>>     int getFoo() { return foo; }
>>
>
> A valid reason for doing things like this is future-proof encapsulation.

That's a non-obvious property worth documenting. If it's a public API guaranteed to never change, that should be stated as such at least to warn against inconsiderate changes.

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

Hear, hear! I start with first with...

public string name;

Then if I really want to change the way the value is assigned or maybe add in some validation, possibly with contracts, I use @property.

(This is only for things which are supposed to be part of the public API anyway.)

I would still document the property, though. I feel I need to justify why every member exists in a struct or class. That's mainly a data layout concern, and that's just how I happen to feel about it.

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.