When writing comment, do you use 1st person?

> I know that originally all Smalltalk comments used 1st person. What is
>  your take on that?
>
> --AA
>
>
> _______________________________________________
> Pharo-project mailing list
> [hidden email]
> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
>

> Adrian Kuhn wrote:
>> I know that originally all Smalltalk comments used 1st person. What is
>>  your take on that?
>
> Martin always writes in first person. :-)
>
> 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.
>
> This bias is built into the language with the keyword "self".
>

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

> 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'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
>
> _______________________________________________
> Pharo-project mailing list
> [hidden email]
> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project