[Pharo-project] I am I am I am ... [WAS] Re: [COTDC] 17 - MCSnapshotReader
Did I already say that I don't like the way Smalltalk classes are documented? yes yes, I know the reasons and the history, but I don't like it. And it is even worst when you read it outside a system browser (like in a webpage or any kind of document). Am I alone? On Wed, Feb 23, 2011 at 9:06 PM, laurent laffont <laurent.laffont@gmail.com>wrote:
hehe, not so much :) http://code.google.com/p/pharo/wiki/CommentOfTheDayContest
14 vs 17
Laurent.
On Wed, Feb 23, 2011 at 8:47 PM, Gary Chambers <gazzaguru2@btinternet.com>wrote:
Was there a difference in the responses? ;-)
Regards, Gary
----- Original Message ----- *From:* laurent laffont <laurent.laffont@gmail.com> *To:* Pharo-project@lists.gforge.inria.fr *Sent:* Wednesday, February 23, 2011 7:20 PM *Subject:* Re: [Pharo-project] [COTDC] 17 - MCSnapshotReader
And I'm plain stupid: we've already done MCSnapshotReader last week :)
Laurent - currently integrating a week of COTDC
On Wed, Feb 23, 2011 at 8:14 PM, Alexandre Bergel < alexandre.bergel@me.com> wrote:
Looks okay in principle. However, 4 tests will turn yellow
Alexandre
On 23 Feb 2011, at 16:03, laurent laffont wrote:
To me it seems this class is useless and that it can be safely removed. The only reference is in MCMczReader>>extractDefinitionsFrom: and it can be replaced by MCReader.
Laurent
On Tue, Feb 22, 2011 at 8:08 PM, laurent laffont < laurent.laffont@gmail.com> wrote: Today: MCSnapshotReader
Comment Of The Day Contest - One Day One Comment Rules: #1: Each day a not commented class is elected. Each day the best comment will be integrated with name of the author(s). #2: If you cannot comment it, deprecate it. Results: http://code.google.com/p/pharo/wiki/CommentOfTheDayContest
Laurent
-- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
On Wed, Feb 23, 2011 at 9:20 PM, Mariano Martinez Peck < marianopeck@gmail.com> wrote:
Did I already say that I don't like the way Smalltalk classes are documented? yes yes, I know the reasons and the history, but I don't like it. And it is even worst when you read it outside a system browser (like in a webpage or any kind of document).
Am I alone?
At the beginning I found it strange. Now I'm used to it and it provides a pattern. The first sentence is usually significant. But feel free to propose another kind of template.... Laurent.
On Wed, Feb 23, 2011 at 9:06 PM, laurent laffont < laurent.laffont@gmail.com> wrote:
hehe, not so much :) http://code.google.com/p/pharo/wiki/CommentOfTheDayContest
14 vs 17
Laurent.
On Wed, Feb 23, 2011 at 8:47 PM, Gary Chambers <gazzaguru2@btinternet.com
wrote:
Was there a difference in the responses? ;-)
Regards, Gary
----- Original Message ----- *From:* laurent laffont <laurent.laffont@gmail.com> *To:* Pharo-project@lists.gforge.inria.fr *Sent:* Wednesday, February 23, 2011 7:20 PM *Subject:* Re: [Pharo-project] [COTDC] 17 - MCSnapshotReader
And I'm plain stupid: we've already done MCSnapshotReader last week :)
Laurent - currently integrating a week of COTDC
On Wed, Feb 23, 2011 at 8:14 PM, Alexandre Bergel < alexandre.bergel@me.com> wrote:
Looks okay in principle. However, 4 tests will turn yellow
Alexandre
On 23 Feb 2011, at 16:03, laurent laffont wrote:
To me it seems this class is useless and that it can be safely removed. The only reference is in MCMczReader>>extractDefinitionsFrom: and it can be replaced by MCReader.
Laurent
On Tue, Feb 22, 2011 at 8:08 PM, laurent laffont < laurent.laffont@gmail.com> wrote: Today: MCSnapshotReader
Comment Of The Day Contest - One Day One Comment Rules: #1: Each day a not commented class is elected. Each day the best comment will be integrated with name of the author(s). #2: If you cannot comment it, deprecate it. Results: http://code.google.com/p/pharo/wiki/CommentOfTheDayContest
Laurent
-- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
Personally, I think the âI amâ formula is very beautiful. You would send a message to someone who says âI am the abstract superclass of all classes that represent a group of elements.â, someone who introduces himself as âThe root interface in the collection hierarchy.â (Java) on the other hand â you might perhaps call a method on him... Though, when writing a comment iâam often not sure if itâs the class or itâs instances that should be the âI amâ speaker? I also read âMy instances are...â which seem correct but less beautiful? Helene. -- View this message in context: http://forum.world.st/I-am-I-am-I-am-WAS-Re-COTDC-17-MCSnapshotReader-tp3321... Sent from the Pharo Smalltalk mailing list archive at Nabble.com.
Hi Mariano--
I know the reasons and the history...
Hm, I don't think I know the history. As far as I can tell, Smalltalk-80 used "the receiver" instead of "I". When did the anthropomorphic style arise?
And it is even worst when you read it outside a system browser (like in a webpage or any kind of document).
I don't think it's particularly worse if you still have the context (which class you're talking about).
Am I alone?
No, I recall a couple of others who didn't like it either. In my experience, though, the vast majority either don't care or like it at least as much as you dislike it. :) Personally, in a system so strongly inspired by biological and verbal metaphors, I think it makes a great deal of sense. -C -- Craig Latta www.netjam.org/resume +31 06 2757 7177 + 1 415 287 3547
"Craig" == Craig Latta <craig@netjam.org> writes:
Craig> Hi Mariano--
I know the reasons and the history...
Craig> Hm, I don't think I know the history. As far as I can tell, Craig> Smalltalk-80 used "the receiver" instead of "I". When did the Craig> anthropomorphic style arise? As I recall, browsing the original ST80rel2 image at Tektronix in 1982 on a magnolia box (68k bitmapped 1024x768 display), I was amused by the class comments that generally all started with "I am ...", or "Instances of me hold ...". I think down in some of the technical parts, "the receiver" was used because it wasn't "self" somehow. But generally, the original image is very "I am"-ish. -- 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.posterous.com/ for Smalltalk discussion
On Thu, Feb 24, 2011 at 3:25 AM, Craig Latta <craig@netjam.org> wrote:
Hi Mariano--
I know the reasons and the history...
  Hm, I don't think I know the history. As far as I can tell, Smalltalk-80 used "the receiver" instead of "I". When did the anthropomorphic style arise?
From at least Smalltalk-80 V2. AFAIA ParcPlace systems started "cleaning up" class comments adding the impersonal style in the Objectworks 2.5 timeframe. The following is derived from the Smalltalk-80 V2 sources:
$ grep "I am " BrouHaHa/XeroxV2.0/Smalltalk-80.sources.lf | wc 82 2232 13441 $ grep "I am " BrouHaHa/XeroxV2.0/Smalltalk-80.sources.lf | sed 's/\..*/./' | pbcopy 'I am a RunArray where each run represents the virtual addresses of a block of contiguous pages. 'I am a code controller that will do an accept even if the text is the same. 'I am an arrayed collection of pointers. 'I am an abstract collection of elements with integers as external keys. Association comment: 'I am a pair of associated objects--a key and a value. Bag comment: 'I am an unordered collection of elements. 'I am a view of a BinaryChoice. BlockNode comment: 'I represent a bracketed block with 0 or more arguments and 1 or more statements. "I am a copy; put me in the right state to browse a hierarchy" 'I am a StandardSystemView that provides initialization methods (messages to myself) to create and schedule the various system browsers: System Browser, System Category Browser, Class Browser, Message Category Browser, Message Browser. 'I am a Switch that turns off automatically after being turned on, that is, I act like a push-button switch. 'I am the text view controller for a change browser. 'I am the controller for ChangeListView, handling the list menu. 'I am a list view of various system changes. 'I am a class used for running static checks over the system. I am created during fileIn in response to "class methodsFor: cat" message. 'I am a change to some part of a class definition (actual definition, comment, name, . 'I am a change to some part of a class comment. 'I am a change to some part of a class definition. 'I am a change related in some way to a particular class. 'I am a TextView that assumes the text is code. Collection comment: 'I am the abstract class of all collection classes. 'I am a FillInTheBlankController that causes termination on a carriage return. 'I am a 16 x 16 dot matrix suitable for use as the current cursor. 'I am used by the decompiler to construct parse tree nodes and other appropriate items corresponding to each unit identified by the decompiler. Dictionary comment: 'I am a set of associations. 'I am a display object which can both paint myself on a medium (displayOn: messages), and can act as a medium myself. if I am displayed at location. 'I am an abstract representation of a collection of FilePages and a reference to a FileDirectory which contains me. fileName <String> The name of the file I am viewing. 'I am a StringHolderController for a FillInTheBlankView. 'I am a view of a FillInTheBlank--I display a query and an area in which the user can type some information. FormButtonCache comment: 'I am used to save information needed to construct the menu for the form editor. IdentityDictionary comment: 'I am a subclass of Dictionary in which the lookup is done using == rather than =. 'I am a SwitchController that has its View (a SwitchView) highlighted while the model (a Switch) handles the messages it is sent. 'I am a StandardSystemView that provides initialization methods (messages to myself) to create and schedule the interface to an object Inspector. 'I am a common abstract superclass for all Integer implementations. LeafNode comment: 'I represent a leaf node of the compiler parse tree. Link comment: 'I am a simple record of a pointer to another Link'! 'I am a kind of ScrollController that assumes that the view is a kind of ListView. 'I am an abstract View of a list of items. LiteralNode comment: 'I am a parse tree leaf representing a literal string or number'! 'I am a kind of ListController that blocks new selections if the model is locked--i. 'I am a SwitchController that will not take control if the model (a Switch) is locked. MappedCollection comment: 'I am re-ordering or subcollecting of a writeable SequenceableCollection. MethodNode comment: 'I am the root of the parse tree. "I am the root of a parse tree; answer with an instance of CompiledMethod. "I am the root of a parse tree; answer with a sorted collection of associations 'I am a Controller that modifies the scheduling of user activities so that the three mouse buttons can be used to make selections or display menus. 'I represent a controller that never wants control. 'I am a kind of MouseMenuController that creates a yellow button menu for proceeding an interrupted process or for creating and scheduling a debugger on the interrupted machine state. 'I am a view of interrupted machine state. 'I am a kind of Switch that can be connected to some related object, typically to a collection of my instances. 'I am a code controller that will not take control unless my model has some selection. 'I am a code view for an OnlyWhenSelectedCodeController. OrderedCollection comment: 'I am an ordered collection of elements. 'I keep track of the current and high position of the stack that will be needed by code being compiled. Point comment: 'I am an x-y pair of numbers usually designating a location on the screen'! PositionableStream comment: 'I assume that my contents is an indexable collection and that, in support of accessing the elements of my contents, I can reposition a pointer. "Since I am not necessarily writable, it is up to my subclasses to override myList <LinkedList> on which I am suspended 'I am a kind of StringHolderController (a ParagraphEditor that adds the doIt, printIt, accept, and cancel commands). 'I am a StringHolderView of the description of a Project. ReadStream comment: 'I am a reader of an indexable collection. ReadWriteStream comment: 'I am a positionable stream into which we can both read and write. 'I am the controller for the parts of the display screen that have no window on them. 'I represent control for scrolling using a scrollBar. SelectorNode comment: 'I am a parse tree leaf representing a selector'! Set comment: 'I am an unordered collection of elements that are not duplicated in me. ["Negate carefully in case I am SmallInteger minVal" SortedCollection comment: 'I am an ordered collection of elements, sorted via the function sortBlock. 'I am a controller for StandardSystemViews, that is, those views that are at the top level of a project in the system user interface. Stream comment: 'I am an abstract class representing objects that stream over a self typing data structure. String comment: 'I am an indexed collection of Characters. 'I am a View of a String that is an aspect of a more structured object. 'I represent a selection setting and actions to take depending on a change in the setting. 'I am a view of a Switch. SystemDictionary comment: 'I am a special dictionary that supports protocol for asking questions about the structure of the system. 'I am a kind of StringHolderController (a ParagraphEditor) that adds the doIt, printIt, accept, and cancel commands. 'I am a StringHolderView of the description of the contents of a TextCollector or Transcript. VariableNode comment: 'I am a parse tree leaf representing a variable. WriteStream comment: 'I am a writer of an indexable collection.
And it is even worst when you read it outside a system browser (like in a webpage or any kind of document).
  I don't think it's particularly worse if you still have the context (which class you're talking about).
Am I alone?
  No, I recall a couple of others who didn't like it either. In my experience, though, the vast majority either don't care or like it at least as much as you dislike it. :)  Personally, in a system so strongly inspired by biological and verbal metaphors, I think it makes a great deal of sense.
It's sweet and cuddly and not a bad thing for all that. The false assumption is that the impersonal style is more informative. It's not intrinsically better, merely plays to our prejudices of what good technical documentation should be; style over substance. The important thing is whether a class comment is useful not whether it is written in an approachable style or not. Persnally I prefer the approachable style, but prefer useful documentation over style any day. 2¢ Eliot
-C
-- Craig Latta www.netjam.org/resume +31 Â 06 2757 7177 + 1 415 Â 287 3547
participants (6)
-
Craig Latta -
Eliot Miranda -
Helene Bilbo -
laurent laffont -
Mariano Martinez Peck -
merlyn＠stonehenge.com