Thelop Dictionary Discussion

From ThelopDictionary


A GENERAL NOTE ON ABBREVIATIONS

Abbreviations should only be used if the abbreviation is not a prefix of any other word that is currently in the dictionary, or likely to be added some day. Many of the abbreviations in the ThelopDictionary fail this test (e.g. Col vs Color).

At least the abbreviations in the ThelopDictionary are documented and used consistently (except for Na and Name). However, it would be better to fully spell out the words if there is any potential for confusion. In many cases you save only a character or two. Typing time is cheap - you already know what you want to type. Time spent understanding a cryptic abbreviation is expensive thinking time that could be better spent elsewhere. It's likely that the time lost looking up abbreviations or trying to remember whether or not a given word is abbreviated will dwarf the time saved by not typing the extra characters.

-- JoshPurinton

I had a long discussion about abbreviations with SunirShah which we should not repeat (ToDo: refactor it to a separate page). My point is, that you can't live without abbreviations: you either abbreviate to a small number of characters (Thelop does for the most common words), or - much worse - to zero characters (names don't show complete semantic content). But you could change my mind by showing me a moderately sized API or project with complete and unabbreviated names. -- HelmutLeitner

The Cocoa API (formally OpenStep / NextStep) is a good sized OO framework that does not use abbreviations in its names. As the years have progressed, the very large MacOs API has changed from using abbreviations to NOT using abbreviations. (There are a few, but fewer than before.) Check out the ln-line documentation at http://developer.apple.com/techpubs/index.html [Should I have said "abbrv" instead of abbreviations?] -- KeithRay

The problem is - as I tried to explain above - that the worst abbreviations are often not visible. A function Show(x,y,z) has not abbreviated words. But what does it show, what parameters does it need and what does it return? Are there side effects? Does the function name really tell the whole story? -- hl

Is Window.show() and Button.show() that confusing? [or ShowWindow?() and ShowControl?() for C API?]


...Cocoa API does not use abbreviations...

Taking a short look into

I found a number of abbreviations
 NSWindow                             // (and dozens of NSXxxx classes)
 Declared in: AppKit/NSWindow.h       // App(lication) NS(???)
 initWithContentRect                  // init(ialize) Rect(angle)
 setMinSize                           // Min(imum)
 setMaxSize                           // Max(imum)
 performMinaturize but setMiniwindowImage  // Mini(aturized)window
 gState                               // g(???)
 disableCursorRects                   // Rect(angle)s
 WindowRef                            // Ref(erence) 

so this doesn't seem to be correct although Cocoa really uses long names (but without consistency). -- hl

---

Then I found the following interesting example:

 "The print method runs the application's 
 Print panel and causes the NSWindow's frame view to print itself"

so why didn't they call the function something like

  printFrameViewUsingPanel

which would fit quite well within their naming scheme. -- hl


CONFUSING ABBREVIATIONS


Ext - Ext is a particularly unfortunate abbreviation. Extent, Extend, Extension, external. There are too many words that begin with this prefix. -- jp


Ind - my first impression: Independent


Dim - my first impression: a verb meaning "to grey out"?


Rep - my first impression: repeat? Report? I still can't remember what it actually means right now as I right this comment without looking it up, and I've been studying this dictionary for hours! Oh, right, it means REPLACE. Argh!


Val - my first impression: valid?


OTHER COMMENTS

-- JoshPurinton


Empty - Empty is also a verb. It seems arbitrary that empty is a property while clear is an action. StringEmpty and StringClear are too close for comfort. How about IsEmpty?


Flag - The example suggests WindowRetVisibleFlag. But this is a lot of words for very little semantic meaning. Why not WindowIsVisible?


In - You say that exchanging the objects is usually better? I would say always. Please give an example where In is to be preferred to exchanging objects and using "Contains". Do not unnecessarily multiply entities (or relationships).


Limit - One example uses a word, glyph, which should perhaps be added to the dictionary?


Lower - How is StringCompareLengthLower different from StringCompareLength?


Na - Get rid of Na. There is no excuse for having an abbreviation that has a different shade of meaning from the word it abbreviates.


Proj - This is a bad idea. If you have to use Proj, it exposes a weakness in your earlier names. For example, the definition of Word can be ambiguous. Better to add modifiers to Word.


CategoryThelop


EditText of this page (last edited November 7, 2005) or FindPage with title or text search