Jan Skibinski <[EMAIL PROTECTED]> wrote,
> On Thu, 23 Mar 2000, Volker Wysk wrote:
> > (Message didn't get through the first time. Reposting.)
> I tried to put an idea across that we do not need any
> tags whatsoever for any of those facilities.
> I really mean it. Neither XML based nor home grown, such as
> triple-dash suggested by Manuel or double stars of Sun - as
> used in Java.
>
> /**
> *
> * They say that the double star supposes to signify
> * the importance of this comment for documentation.
> *
> */
>
> I say that any comment that is not properly positioned
> in the module structure should be ignored. It is not
> worthy of our attention; it either signifies an
> implementation hack or its author's frivolity. We only need
> one type of comments - good and important comments.
> The rest is a trash. If you accept this, the double
> star is gone. We just got rid of one tag.
The importance of a comment was not the point of my
comment. In any well documented module there are two types
of comments: (1) Those for users of the module and (2) those
that are only for the implementors of the module.
Category (2) is not suitable for the users as they either
often are not interested in the details of the
implementation or because an abstract barrier is to be
preserved. Consequently, you have to distinguish the two.
> I see only a need for two or three types of comments.
> Module comments just after exports. Function comments
> just after the function signatures. Possible
> class comments just after a class declaration.
> Maybe data/newtype/type comments too...
>
> I say "after", not "before". For Ross and Manuel
> the "before" seems to be the obvious and natural
> solution.
[..]
> If I do it other way around
> then I find myself in a typical "C" trap:
>
> /**
> *
> * Function: void fillToBorder (
> * Point p,
> * Color fillColor,
> * Color borderColor);
> *
> * Formalized or very loose comment here: with or
> * without special tags.
> *
> */
>
> void fillToBorder (
> Point p,
> Color fillColor,
> Color borderColor)
> {
> ...
> }
>
> My experience teaches me that more often than not
> programmers change their mind and modify the
> number of arguments to their functions. And they
> often forget to modify the comments above their point
> of focus. From then on the original comments are not
> only useless but also misleading if extracted
> as API.
Duplicating the function signature in the comment is a bad
idea, but it has nothing to do with whether the comment is
before or after the signature. I would write,
// Flood a portion of the image with `fillColor',
// beginning at point `p' and stopping at
// `borderColor'.
//
void fillToBorder (
Point p,
Color fillColor,
Color borderColor)
{
...
}
The reason is simple: Move from the abstract to the
concrete. First I want a rough idea about what the function
does, then the formal signature.
Manuel
