[Twisted-Python] Lies, Damn Lies, and Stable Interfaces
glyph at twistedmatrix.com
Tue Jun 17 21:17:16 EDT 2003
On Tuesday, June 17, 2003, at 03:36 PM, Bob Ippolito wrote:
> I'm also not fond of the "mind" terminology, there's gotta be a better
> word for what it is.. entity, participant, client, user, foobar
> (prefix anything with "remote" if desired).. but not "mind".
The naming scheme is somewhat baroque on purpose. Cred's domain is a
_very_ semantically polluted one, where (A) the concepts are subtle and
complex and (B) most all the *normal*-sounding names are already used
by some other project or related concept to mean something apparently
similar but in reality very confusingly different.
"Mind" is, honestly, the best word I've heard so far that will
adequately distinguish the object in this role from other, similar
objects which may be implemented as domains for a particular protocol.
When a simple or compound word will do, I try to use it.
"CredentialChecker", for example, doesn't need to be "Portcullis"
because its name unambiguously describes its function.
However, compound words like ClientProxy, AvatarClient, ClientObject,
RemoteMethodEventHandlerProxyHandler and so on are very easy to
misunderstand, especially (as many folks I'm sure do) if you have had
experience with a similar system in a proprietary environment with its
own naming quirks.
In short: in a system which involves subtle concepts, I prefer names
which are memorable and unambiguous. If possible, the terms should
also be clear, but as users develop experience with the system, the
initial clarity is less and less important but memorability remains
just as important.
As an added bonus, if a term's actual meaning is subtle -- and. if and
ONLY if the documentation is good -- the bizarre naming will force a
new user to read the documentation to get a handle on what it means.
While it would be nice to be able to clearly express to a user what a
term means with only its name, it is better to have them confused and
encouraged to read documentation than to have them _think_ they
understand what it's supposed to do and be far more confused later when
an apparently obvious interaction has some exceptionally bizarre
More information about the Twisted-Python