[Twisted-Python] Lies, Damn Lies, and Stable Interfaces

[Glyph Lefkowitz]

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 
side-effects.