Re: Question about handles

[Don Blaheta <blahedo blahedo org>]

Quoth Sameer Sahasrabuddhe:
> On Tue, Jul 29, 2008 at 4:21 AM, Don Blaheta <blahedo blahedo org> wrote:
> > > There are two specialized objects involved in building a connection. One is
> > > a Handle, the other one is a ConnectionPoint. In an existing connection
> > > between two DiaObject the Handle belongs to the first ("connected to") and
> > > the ConnectionPoint belongs to second ("connected by").
> >
> > Note: the word "connected" is passive in both "connected to" and
> > "connected by".  Part of what I found confusing about the exchange was
> > that Hans seems to find the to/by distinction obvious, whereas to me it
> > seems rather arbitrary and *quite* at odds with the natural English
> > interpretations of those phrases.
>
> Actually, from what I can remember about grammar back from school
> days, it's not the voice that is needed here, but the case. A line
> connects two objects. So the line is the connector (nominative case)
> while the objects are the connectees (objective case).

Case is not it either: both "connector" and "connectee" are nouns, which
can be in any case---not that English even marks case on anything but
pronouns.  There is no syntactic distinction between the two things
we're talking about.  There is, to some extent, a distinction in the
semantic role (agent, patient), particularly when you cast it as
"connector" and "connectee".  However, the real problem in our English
descriptions, and this only became clear to me after I did up that
diagram I posted about earlier, is that there's really two different
relationships we're talking about here, both in English and in Dia:

* One is a zero-dimensional "connection", ie at a single point, and is
  asymmetric in that we talk of "connector" and "connectee"---in Dia,
  these are represented by a Handle and a ConnectionPoint respectively.
  "Connected to" makes sense in this context.  Variables and type names
  used in Dia to represent aspects of this include Handle,
  ConnectionPoint, connected, connections, and connected_to.

* The other is a one-dimensional "connection", ie a line-ish thing that
  connects two or more other things.  This is symmetric, in that it has
  two ends (with a zero-dimensional "connection" at each), although each
  end can have its own properties with respect to how they're drawn.
  This is the sense that "connected by" suggests in English, which is
  why the earlier discussion was so confusing.  Variables and type names
  used in Dia to represent *this* concept include Connection and
  connection.

> So here's what it looks like to me, using my own names ...

I started out thinking this was a semi-OT discussion, that we'd never
want to go through renaming everything, but the more I reflect on this,
the more I think a mass renaming is a good idea.  Sorting through the
nest of pointers is confusing enough without also having to sort through
a bunch of similar variable names that almost correspond to two
different senses of a polysemous word. :P  So, onward:

> So here's what it looks like to me, using my own names instead of the
> "to / by" confusion. When a handle on a line is connected to a
> ConnectionPoint on a box, we have the following.
>
> 1) handle->connectees should be the list connection points connected
> to that handle (i think this is currently implemented as
> handle->connected_to)

Except that there can only be at most one connection point attached to a
single Handle, or rather, a Handle can be connected to at most one
ConnectionPoint.  So handle->connectee would be more appropriate.

> 2)connectionPoint->connectors should be the list of handles connected
> to that connection point (curently ConnectionPoint->connected_by)

Ok.

> If this is true, then it's also natural that:
>
> 3) handle->owner should point to the line

Oddly enough, Handles don't currently have owners.  Although, if you had
to, you could follow the links round to get there.

> 4) ConnectionPoint->owner should point to the object that owns the
> point (currently ConnectionPoint->object, which is definitely poor
> naming, notwithstanding the expressive power of English)

That's sort of a separate naming issue.  On the one hand, the object
variable in Element is "this" object in the OO paradigm (specifically,
the superclass instantiation), and that's not what the object variable
in ConnectionPoint is doing; "owner" would be a more descriptive name.
On the other hand, any CP is uniquely and permanently associated to a
single DiaObject, so you could make a case that the name "object" is
appropriate.  The situation is not sufficiently clear-cut that I'd want
to include it in a general connect{or,ee,ed,ed_to,ion,ions,ionpoint}
renaming.

> In a connection, I am not sure who owns the connectionPoint. From an
> earlier comment made by Hans, it seems that many objects can be
> associated with a single ConnectionPoint, which makes no sense to me.

Many Handles can connect to a single ConnectionPoint, and so in that
sense many objects can be "associated with" a single CP, but each CP is
only part of one DiaObject.

> So its seems that number four is currently implemented as
>
> 4a) ConnectionPoint->connected which is the list of objects connected
> at this point (but not the owner of the handle).

I'm not sure what you mean by this.


I like your idea of renaming with "connectee" and "connector" but if
we're going to do that level of renaming we might as well go all the
way.  Particularly given my observation regarding the multiple English
meanings of "connection", I'd like to do a renaming that removes one or
both senses from the Dia codebase.  Conceivably, "Handle" could be
involved in the renaming as well, but that's not really necessary (and
Handle is a great name for the primary purpose of the thing, namely,
places to grab and resize/reshape the object).  Of "Connection" (the 1D
kind) and "ConnectionPoint" (the 0D kind), I think the former is a
better match for the English meaning; plus, I can think of a great, less
ambiguous name for a ConnectionPoint: an AttachmentPoint.  So here would
be my proposed renaming (unrenamed things I've left blank, but put them
in the list to make counterproposals easy, and easy to compare):

Handle                          => 
Element.resize_handles          => 
Connection.endpoint_handles     =>
DiaObject.handles               => 

ConnectionPoint                 => AttachmentPoint
Handle.connected_to             => Handle.attached_at
ConnectionPoint.connected       => AttachmentPoint.attached_handles
DiaObject.connections           => DiaObject.attachment_points
ConnPointLine                   => LineAttachments
ConnPointLine.connections       => LineAttachments.attachment_points
Box.connections (and similar)   => Box.attachment_points

Connection                      =>
Line.connection                 =>


Thoughts?

-- 
-=-Don Blaheta-=-=-blahedo blahedo org-=-=-=-<http://www.blahedo.org/>-=-
C: Unintelligible code means job security.