On Mon, Dec 28, 2009 at 5:56 AM, Martin McClure
<martin@hand2mouse.com> wrote:
Adrian Kuhn wrote:
> Martin McClure <martin@...> writes:
>
>> Actually, I usually do prefer to use first person when writing Smalltalk
>> comments. I find that anthropomorphizing objects helps to think in an
>> object-oriented way.
>
> Thanks everyone for all the answers so far!
>
> One of the things that keep confusing me is whether the I refers to the class,
> �the object or (in a method comment) to the method or even the method
> �activation? For example in Randal's example, there it is the the behavior
> �*class* speaking in first person. Whereas to my understanding in
> �*object*-oriented programming the objects should talk be first person (not the
> �classes).
>
> Even more confusing, I have also seen comments where the it was the object or
> �the methods. Or most confusing, an amalgamation of both, as eg in "I return my
> �first element" where to be precise the method activation returns the first
> �element of the object. So shouldn't it either be "(When activiated) Returns my
> �first element" or "I return the first element of my reciever"?
>
> This is not an academic example. When I started to write comments for SUnit, I
> �got actually confused. When writing (instance/class) methods comments, to whom
> �does the "I" refer to?
>
Good points. Existing comments are not always consistent.
In my opinion, "I" should always refer to an object. Which object?
"Self" within the current context. In an instance-side method comment,
"I" is the receiver of the message. In a class-side method comment, "I"
is the class. In a class comment, it's a little less clear, but probably
"I" should be the class in that case.
I often write "My instances" for class comments.
�
I'd probably write the above example imperatively, something like
"Answer my first element".
In Smalltalk, I also tend to prefer "answer" over "return", and I tend
to talk about "messages" instead of "methods" unless explicitly dealing
with method objects.
Regards,
-Martin