Commenting Methods: Imperative Tense or Present Tense?

Hello Forum,

I've noticed that some Smalltalkers prefer to comment methods in the
imperative, while others in the present.  For example:

#colorOfSomethingOrOther: something
        "Answer the color of...  If something does not exist, then
raise..."

versus

#colorOfSomethingOrOther: something
        "Answers the color of... If something does not exist, then
raises..."

Is there a consensus in the Dolphin community as to which is better, or
is simply a matter of being consistent whichever tense one chooses?

In proofreading my comments for grammatical and spelling errors, I
noticed that I've mixed tenses.

Cheers,

Eric

Eric,

> Is there a consensus in the Dolphin community as to which is better, or
> is simply a matter of being consistent whichever tense one chooses?

I don't think there is a consensus.

I use a descriptive style myself "answers a number..." (which is also the style
that Sun recommend for Java -- not that that influences me).  I think OA have
standardised on an imperative style, which works perfectly well too.

I don't think it makes a lot of difference really, even if you are a bit
inconsistent.   Generally I consider myself lucky to have comments to read at
all...


Another difference between the OA style and my own, is that they like to use
the coldly formal:
    the receiver
whereas I prefer the more human:
    we

;-)


The only style that really grates is sometimes seen in older Smalltalk code
where comments (often class comments) are of the form:

    I do <such and such>

Which, IMO, is just pathetic -- like a dog sitting on its back legs with a
collecting bowl in its jaws....

    -- chris

Chris,

>
Another difference between the OA style and my own, is that they like to
Use the coldly formal: the receiver...
>

Yes, and this style can confuse the newcomer a bit initially, but I've
started using it myself.

One _could_ take the perspective that newcomers should use the
imperative, while experts should use the descriptive: "Answer the
node... (pretty please with cherries on top)" versus "Answers the
node... (how I know you will)."

:-)

Cheers,

Eric

or
> > is simply a matter of being consistent whichever tense one chooses?
>
> I don't think there is a consensus.
>
> I use a descriptive style myself "answers a number..." (which is also
the
> style
> that Sun recommend for Java -- not that that influences me).  I think
OA
> have
> standardised on an imperative style, which works perfectly well too.
>
> I don't think it makes a lot of difference really, even if you are a
bit
> inconsistent.   Generally I consider myself lucky to have comments to
read
> at
> all...
>
>
> Another difference between the OA style and my own, is that they like
to with a
> collecting bowl in its jaws....
>
>     -- chris

Clearly, the imperative is a bit shorter.

In a class-comment it might seem to makes sense
that the object is 'speaking' in the first term
when presenting its services.

But in general I would like to emphasize the point
that whoever is 'speaking' is really the programmer
who wrote the comment. Often multiple programmers
make changes to the same method, and it is useful
if you can later track down the individuals who
modified the code, to ask them why and how.

-Panu Viljamaa

Chris Uppal wrote:

> The only style that really grates is sometimes seen in older Smalltalk code
> where comments (often class comments) are of the form:
>
>     I do <such and such>
>
> Which, IMO, is just pathetic -- like a dog sitting on its back legs with a
> collecting bowl in its jaws....

Well I guess it's literally pathetic - as in "pathetic fallacy".

Is is so bad to think of Smalltalk as a friendly little pal inside the
comptuter? After all - I already think of Perl as an aggressive recently
deinstutionalised street person who's cornered me on public transport.

As for commenting style - I've standardised on "wildly inconsistent".

>     -- chris



                Steve

Steve,

[me:]
> >     I do <such and such>
> >
> > Which, IMO, is just pathetic -- like a dog sitting on its back legs
> > with a collecting bowl in its jaws....
>
> Well I guess it's literally pathetic - as in "pathetic fallacy".

Nice!


> Is is so bad to think of Smalltalk as a friendly little pal inside the
> comptuter?

I have /nothing/ against anthopomorphising objects -- I do it all the time,
including in comments.  The "we" in my commentary refers to the group: you (the
reader), me (the writer), and the object itself, all travelling together.  (You
and I looking over its shoulder as it goes about its business.)

But I do think that pretending that the object is capable of reasoned
discourse, and that there is no writer at all, is going a little too far...


> After all - I already think of Perl as an aggressive recently
> deinstutionalised street person who's cornered me on public transport.
>
> As for commenting style - I've standardised on "wildly inconsistent".

<grin/>

    -- chris

Chris,

No arguments with anything you said, except...

> The only style that really grates is sometimes seen in older Smalltalk code
> where comments (often class comments) are of the form:
>
>     I do <such and such>
>
> Which, IMO, is just pathetic -- like a dog sitting on its back legs with a
> collecting bowl in its jaws....

Let's be fair, the dog is showing some ingenuity ;)

Have a good one,

Bill


--
Wilhelm K. Schwab, Ph.D.
[hidden email]