Best Practices in Naming Conventions: Revisiting an Old Forum Post

Hello Forum,

Back in August of 1997, a post was made concerning the consistency of
naming conventions in view aspects.  The replies to that post sort of
leaves one with the impression that the conventions were still be
revolved.

Has the Dolphin community settled yet on naming conventions for these
terms: 'caption,' 'title,' 'name,' and 'text'?  This question was raised
here (O.K., a brawl broke out) internally when, in fleshing out a menu
abstraction layer, we attempted to name the variable that would hold the
portion of text that the user sees as the "menu item" on a menu.

So, what's in a name?

Cheers,

Eric

Eric,

> Has the Dolphin community settled yet on naming conventions for these
> terms: 'caption,' 'title,' 'name,' and 'text'?  This question was raised
> here (O.K., a brawl broke out) internally when, in fleshing out a menu
> abstraction layer, we attempted to name the variable that would hold the
> portion of text that the user sees as the "menu item" on a menu.

If I remember correctly, then I think you'll find there's some confusion in the
way that commands and textual indications are related in Dolphin's command
framework.  IMO, a command (I forget the actual class/protocol name) should
have several independent aspects:

1)    the command itself
2)    an optional textual representation of the command
3)    an optional graphical representation of the command
4)    an optional textual description of what the command does

(2) would be used as menu text, button text, and as the text to display in
toolbars when the buttons have displayed text.

(4) would be used for tooltip text for [toolbar] buttons, and as status-bar
helper text for meny items (a useful feature but not provided by the Dolphin
framework).

Unfortunately, the framework conflates (2) and (4), which is both limiting and
potentially confusing.  Ideally the four would be separate, and would have
separate selectors (#command, #text, #image, #description seem a sensible set
of names), but that's not how it works.

    -- chris

Hello Chris,

>If I remember correctly, then I think you'll find there's some
confusion in >the way that commands and textual indications are related
in Dolphin's >command framework.

It is a little confusing, yes, but I'm not so sure it could be anything
but confusing.  I have found this problem in every framework; indeed, my
own history of classes developed over the years exhibit the same
problems.  Eiffel's approach is confusing precisely because it tries too
hard not to be: descriptors are far too common-denominator.

I've stopped wrestling with the issue on cerebral terms.  I suppose I'm
only looking for consistency now.  One can call a hat a tit-for-tat, so
long as one does so consistently :).

>#command, #text, #image, #description seem a sensible set of names...

I agree, except one of my peers here would have a problem with #text,
preferring #title instead.  #label could be a good alternative.


Cheers,

Eric


> -----Original Message-----
> From: Chris Uppal [mailto:[hidden email]]
> Posted At: Sunday, June 04, 2006 6:22 AM
> Posted To: comp.lang.smalltalk.dolphin
> Conversation: Best Practices in Naming Conventions: Revisiting an Old
> Forum Post
> Subject: Re: Best Practices in Naming Conventions: Revisiting an Old
Forum
> Post
>
> Eric,
>
> > Has the Dolphin community settled yet on naming conventions for
these
> > terms: 'caption,' 'title,' 'name,' and 'text'?  This question was
raised
> > here (O.K., a brawl broke out) internally when, in fleshing out a
menu
> > abstraction layer, we attempted to name the variable that would hold
the
> > portion of text that the user sees as the "menu item" on a menu.
>
> If I remember correctly, then I think you'll find there's some
confusion
> in the
> way that commands and textual indications are related in Dolphin's
command display in
> toolbars when the buttons have displayed text.
>
> (4) would be used for tooltip text for [toolbar] buttons, and as
status-
> bar
> helper text for meny items (a useful feature but not provided by the
> Dolphin
> framework).
>
> Unfortunately, the framework conflates (2) and (4), which is both
limiting
> and
> potentially confusing.  Ideally the four would be separate, and would
have
> separate selectors (#command, #text, #image, #description seem a
sensible
> set
> of names), but that's not how it works.
>
>     -- chris