[swift-evolution] [Review] SE-0023 API Design Guidelines

[Dave Abrahams]

on Sun Jan 24 2016, Charles Kissinger <swift-evolution at swift.org> wrote:

>> This discussion of acronyms does raise a different issue, though. I
>> would suggest expanding the “Avoid abbreviations” section of the API
>> Design Guidelines a bit to make a clear distinction between
>> truncating words just to shorten identifiers (bad) and using common
>> acronyms (good). You don’t want people thinking they’re being
>> advised to do this:
>> 
>> var hyperTextMarkupLanguageElement = HyperTextMarkupLanguageElement()
>
> Sorry, I think my over-the-top example completely undermined the point
> I was trying to make. “HTML” and other common acronyms are clearly not
> being discouraged in the current guideline. But there is no acronym so
> obscure it can’t easily be found on the internet. So what
> abbreviations are you discouraging? Truncations like Str or Len? Or is
> this guideline really just about acronyms and not making up your own?
> I just thought it could be more clear.

The use of initialisms like HTML falls under the "term of art" clause.
That is the common usage; probably at least 100x more people have an
idea what HTML is than have ever heard the phrase "hypertext markup
language."

We could try to add a cross-reference to the guidelines every time a
countervailing concern might cause you to make a different choice.  I'm
not sure wheter that would make the guidelines better, or just make them
too complex to understand (honestly not sure).

-- 
-Dave