[Pharo-project] 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
Hi Adrian, I think the person term in "First person" refers more to a human than any artificial intelligence form, which anyway is methaphysically impossible. Cheers, Hernán 2009/12/27 Adrian Kuhn <akuhn@iam.unibe.ch>:
I know that originally all Smalltalk comments used 1st person. What is  your take on that?
--AA
_______________________________________________ Pharo-project mailing list Pharo-project@lists.gforge.inria.fr http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
"Hernán" == Hernán Morales Durand <hernan.morales@gmail.com> writes:
Hernán> I think the person term in "First person" refers more to a human Hernán> than any artificial intelligence form, which anyway is methaphysically Hernán> impossible. And yet, through anthropromorphism, this is exactly how the early Smalltalkers talked and wrote their comments. See the class comment for "Delay", for example: I am the main way that a process may pause for some amount of time. The simplest usage is like this: (Delay forSeconds: 5) wait. Or "Behavior": My instances describe the behavior of other objects. I provide the minimum state necessary for compiling methods, and creating and running instances. Most objects are created as instances of the more fully supported subclass, Class, but I am a good starting point for providing instance-specific behavior (as in Metaclass). I can imagine these comments date back to the original ST80 image. The question on the table is, should this practice continue. I vote yes. I found this style of comments a refreshing change, and also forced people into thinking about what a class *does*, not just what it *holds*. -- Randal L. Schwartz - Stonehenge Consulting Services, Inc. - +1 503 777 0095 <merlyn@stonehenge.com> <URL:http://www.stonehenge.com/merlyn/> Smalltalk/Perl/Unix consulting, Technical writing, Comedy, etc. etc. See http://methodsandmessages.vox.com/ for Smalltalk and Seaside discussion
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". Regards, -Martin
2009/12/28 Martin McClure <martin@hand2mouse.com>:
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".
+1 I find it more encouraging for use , when classes has comments written in a 1st person style. Because, psychologically, i feel that i can trust to delegate certain tasks to given object, while if i read a 3rd person comments, i am usually think that this is a part of something bigger, which is incomplete (wont work) alone, and so, i should use it carefully.
Regards,
-Martin
_______________________________________________ Pharo-project mailing list Pharo-project@lists.gforge.inria.fr http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
-- Best regards, Igor Stasenko AKA sig.
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? --AA
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
In SBE we pay extreme attention between message and methods. You send messages, execute a method.
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 Pharo-project@lists.gforge.inria.fr http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
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
_______________________________________________ Pharo-project mailing list Pharo-project@lists.gforge.inria.fr http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
-- Cheers, Peter
participants (7)
-
Adrian Kuhn -
Hernán Morales Durand -
Igor Stasenko -
Martin McClure -
merlyn＠stonehenge.com -
Peter Hugosson-Miller -
Stéphane Ducasse