Thelop Dictionary Discussion

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?]

No, that's quite ok. But there may be situations where a simple show is not enough. Look at the print example below. -- hl

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

I can only try to justify this choice.
First of all: LOP is about a reduced vocabulary. Not each English word is a candidate, only those that are actually used and that contribute something special. This is especially true for verbs.
In this sense one might find that the verb "extend" isn't really needed because it is too vague. What do you extend? Do you ...SetSize? Do you ...AddSomething?
External pairs nicely with
Internal which can't be abbreviated (Int = integer) and external is a rarely used modifier (the least important word class).
Extent is found in graphic-related APIs, so it is more specialized. It is also short and needs the abbreviation less than Extension. -- hl

Ind - my first impression: Independent

Thelop is a language of it's own. It doesn't matter if there are words whose meaning have to be learned. It may take an hour to get used to.

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

As above. This association is from everyday language. Even on reading ArrayGetDim the first time you can't misunderstand it as a verb.

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!

I'm with you. I experimented with Rep/Replace. The word is not so common as I thought initially.

Val - my first impression: valid?

Perhaps an unnecessary abbreviation. Both words are short. Value is used more often.

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?

One might see "Empty" as a slang verb for the better "IsEmpty" and deprecate it.
The verb empty is a relict from early Thelop, when a verb was not yet necessary for a valid Thelop function name (like ObjectSize() instead of ObjectRetSize()).
On the other hand, empty is a weird word. It is necessary and much used but its semantic content is not quite clear.

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

I agree, although the two functions don't seem to be semantically equivalent.
For some reason I avoid the word "Is". It is too easy to misuse. I think if you gave me a list of functions using "Is" I would suggest different ("better") names for 90% of them.

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).

You may be right. I'm only not so sure about being right to use the word "always".

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

The dictionary given is only about 50% of the current standard dictionary. Glyph is a rare word that would typically be part of the project dictionary extensions. It crept in, sorry.

Lower - How is StringCompareLengthLower different from StringCompareLength?

It says "case insensitive" without using an extra word.

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.

"Na" is slang for "ByName". So you can FileAppStr(f,line) if you have a file handle and FileNaAppStr("this.log",line). If you think about FileNameAppStr(name,str), it is not clear whether the string adds to the name or to the file...
Slang may look strange in a system striving for consistency. But I think it adds a human touch. It adds a dimension for conflict, discussion and thinking. Just like the abbreviations force us to think about the words and not just used them, and remind us that Thelop is not just about using English words.

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.

It is an "escape" word. But sometimes you need a little time to find the better solution. There are a number of possible solutions. But you are right, it is better to avoid "Proj".

CategoryThelop