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

[Dave Abrahams]

on Sun Jan 31 2016, Erica Sadun <swift-evolution at swift.org> wrote:

>> On Jan 30, 2016, at 8:49 PM, Dave Abrahams via swift-evolution
>> <swift-evolution at swift.org> wrote:
>> 
>> 
>> on Fri Jan 29 2016, Erica Sadun <swift-evolution at swift.org> wrote:
>> 
>>> It suddenly occurs to me it's almost the 31st and I haven't actually
>>> responded to the proposal as a proposal. 
>> 
>> Thanks for taking the time to do this, Erica.  I'm going to take issue
>> with some of your feedback below, but please know this is motivated by a
>> desire to make the most of your contribution.  I think your feedback is
>> valuable, but much of the signal is getting lost.
>
> No worries. "Low SNR" is my street name.
>
>>> First, I'd entirely eliminate the guidance in the "Be Grammatical"
>>> section and move the section with boolean assertions and property
>>> names to Special Instructions.
>> 
>> I *think* I may know why you want to eliminate the first part, but I
>> have no clue why you think it'd be better to move the other part.
>> Statements like these don't really provide much useful feedback, because
>> we can't tell what problems you think you're solving.
>
> I consider the great Hungarian war settled and am happy with its outcome
> as discussed in the other email.
>
>>> * The protocol question is big and wide as well, and I have written
>>> on-list: it's not "the role of a protocol to describe implementation
>>> details...Going that way leads you to over-designated hungarian-esque
>>> guidelines that I'd rather keep loose, friendly, and sensible."
>> 
>> You have written that, but nothing in the guidelines suggests describing
>> implementation details.
>
> I think this mostly got settled under separate thread. Pulling stuff together.
>
> The guidance says: "Protocols that describe what something is should
> read as nouns (e.g. ).  Protocols that describe a capability should be
> named using the suffixes , ible , or ing (e.g. Equatable ,
> ProgressReporting )."

You dropped aout "able" before the comma.

> Nitpickage: 
>
> "should be named using -ble or -ing suffixes (e.g. Equatable,
> ProgressReporting)". (no "a/i" mismatch, easier to read,
> http://thespellingblog.blogspot.com/2008/12/spelling-words-ending-in-able-and-ible.html)

I don't understand how that improves things.  Some words just *do* use
an "ible" form (e.g. fallible)

> Substance, mostly picking up from stuff you've said in response:
>
> Protocols should express well-defined, testable semantics. Their names
> should express those semantics in a clear and succinct matter.,
> specifically by naming what a conforming type is (use nouns), does
> (use -ing suffixes), or a capacity it provides (use -ble
> suffixes). For example, a protocol can be a `Collection` or
> `DataSource`. It can do `ProgressReporting` or
> `DownloadProcessing`. It can provide the capability for being
> `Equatable` or `IntegerInitializable`.

That seems like a nice addition.

> Additionalage:
>
> Matthew J and I add: https://github.com/apple/swift-evolution/pull/60
> <https://github.com/apple/swift-evolution/pull/60> to introduce
> precise conventional
> meanings for conversion suffixes. (Createable, Convertible, Representable), which I'd love for you to consider
> under the SE-0023 API Design Guidelines review. I think it's applicable.

Yes, let's get that on the review schedule after this.

>>> 
>> * With regard to argument labels, I'd like to add two rules,
>>> as detailed in-thread and written about here: ArgumentLabels.md
>>> <https://github.com/erica/SwiftStyle/blob/master/ArgumentLabels.md>
>>> 
>>> Differentiate related calls whose implementations are distinguished by
>>> their parameters, as you would with initializers, using first
>>> parameter labels. Instead of loginWithUserName("blah", password:
>>> "...") and loginWithCredential(myCredential), prefer:
>>> 
>>> login(userName: "blah", password: "...")
>>> login(credential: myCredential)
>>> This approach emphasizes the action being taken (login) and demotes
>>> the actual arguments involved in performing that action. In doing so,
>>> they require labels to differentiate which implementation of that
>>> action is to be used.
>>> 
>>> and
>>> 
>>> Prefer external names for the first parameter when the natural
>>> semantic relationship between the parameters is stronger than their
>>> relation to the operation.
>> 
>> That rule doesn't work for any one-parameter methods, unless you think
>> they should never have first argument labels.
>
> The rule only applies to tightly coupled arguments so by definition there have to be at least 2 of them
> for this rule to make any sense.
>
>> 
>>> For example, the following calls use labels for the first parameter:
>>> 
>>> login(userName: "blah", password: "...")
>>> moveTo(x: 50.0, y: 30.0)
>>> constructColor(red: 0.2, green: 0.3, blue: 0.1)
>>> 
>>> This example is contrary to Swift's normal naming scheme which
>>> integrates the first argument into the function or method name, for
>>> example:
>>> 
>>> loginWithUserName("blah", password: "...")
>>> moveToX(50.0, y: 30.0)
>>> constructColorWithRed(0.2, green: 0.3, blue: 0.1)
>>> 
>>> The relationships between (x, y), (username, password), and (red,
>>> green, blue) are strong enough to allow you to make a judgement call
>>> to employ an external label.
>>> 
>>> The following shows a counter-example.
>>> 
>>> addLineTo(p1, withWidth: 25.0)
>>> 
>>> In this call, the point and width have no natural
>>> relationship. There's no reason to create an external label for the
>>> first argument so this example follows the standard Swift call
>>> approach.
>> 
>> Thanks again for your feedback, Erica.  If you'd care to clarify any of
>> the points above, that'd be extra awesome.
>> 
>> -- 
>> -Dave
>> 
>> _______________________________________________
>> swift-evolution mailing list
>> swift-evolution at swift.org
>> https://lists.swift.org/mailman/listinfo/swift-evolution
>
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution

-- 
-Dave