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

[Erica Sadun]

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

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)

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

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.

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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160131/aa426017/attachment.html>