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?

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.

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 <[hidden email]> 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
<[hidden email]> <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 <[hidden email]> 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.


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