[Review] SE-0023 API Design Guidelines

Agreed. There are also operations that are not naturally verbs. That's
why we still haven't changed unionInPlace in SetAlgebraType, for
example. The “InPlace” suffix convention is the best thing I've come up
with for handling these scenarios.

···

on Fri Jan 22 2016, Joe Groff <swift-evolution@swift.org> wrote:

      + When a mutating method is described by a verb, name its
      non-mutating counterpart according to the “ed/ing” rule,
      e.g. the non-mutating versions of x.sort() and x.append(y) are
      x.sorted() and x.appending(y).

This is a nice rule in theory, but English fights it with the full
fury of its irregularity. There are a lot of common operations whose
past tense shares a spelling with the infinitive—'split', 'cut',
'read', and 'cast' immediately come to mind. How do you handle naming
non-mutating versions of these operations? Conjugating other irregular
verbs also imposes a barrier on developers whose first language is not
English.

--
-Dave

Uses of non-mutating methods should read as noun phrases when possible, e.g. x.distanceTo(y), i.successor().

This seems to indicate (to me) that e.g. Optional.map and should be
renamed to Optional.mapped? Except that ‘map’ in this case could be
considered a ’term of art’.

Yes, that's the rationale for keeping names like “map” and “flatMap” as
they are.

Would it make sense to add to add some kind of guidance on how to
weigh the individual guidelines when they are conflicting?

I don't think so. First, I think it's probably impossible to come up
with good guidance for that; at some point it's a matter of using
judgement. Second, we want to keep the guidelines as simple as
possible, so they're easy to follow.

···

on Fri Jan 22 2016, Thomas Visser <swift-evolution@swift.org> wrote:

Thomas

On 22 Jan 2016, at 22:02, Douglas Gregor via swift-evolution >> <swift-evolution@swift.org> wrote:

Hello Swift community,

The review of SE-0023"API Design Guidelines" begins now and runs
through January 31, 2016. The proposal is available here:

https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md
<https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md&gt;
Reviews are an important part of the Swift evolution process. All
reviews should be sent to the swift-evolution mailing list at

https://lists.swift.org/mailman/listinfo/swift-evolution
or, if you would like to keep your feedback private, directly to the
review manager. When replying, please try to keep the proposal link
at the top of the message:

Proposal link:

https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md
<https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md&gt;
Reply text

Other replies
<GitHub - apple/swift-evolution: This maintains proposals for changes and user-visible enhancements to the Swift Programming Language. goes into a review?

The goal of the review process is to improve the proposal under
review through constructive criticism and, eventually, determine the
direction of Swift. When writing your review, here are some
questions you might want to answer in your review:

What is your evaluation of the proposal?
Is the problem being addressed significant enough to warrant a change to Swift?
Does this proposal fit well with the feel and direction of Swift?
If you have used other languages or libraries with a similar
feature, how do you feel that this proposal compares to those?
How much effort did you put into your review? A glance, a quick reading, or an in-depth study?
More information about the Swift evolution process is available at

https://github.com/apple/swift-evolution/blob/master/process.md
<https://github.com/apple/swift-evolution/blob/master/process.md&gt;
Thank you,

-Doug Gregor

Review Manager

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

--
-Dave

_______________________________________________ swift-evolution mailing list swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

Current:

  * Use imperative verb phrases for mutating methods: x.reverse(), x.sort(), x.tweak()
  * Use noun phrases for non-mutating methods: x.distanceTo(...), idx.successor()

Proposed:

  * Use verb phrases to declare procedural methods, whether or not they mutate an instance or just produce side
    effects: x.reverse(), x.sort(), x.tweak(), x.perform(), x.dispatch(), x.send()
  * Use noun phrases to describe values returned by a functional method: x.distanceTo(y), index.successor() (This
    admittedly leaves further issues around other functional methods, for example, seq.separatedBySequence(seq) and
     int.strideTo(other: Self, step:Self.Stride), etc. )

I suggest that mutating methods are just a procedural method (side effect, no return value) vs functional.

Hi Erica,

When you propose a change, could you please explain why you think your
change is an improvement?

Thanks,
Dave

···

on Fri Jan 22 2016, Erica Sadun <swift-evolution@swift.org> wrote:

-- E

    On Jan 22, 2016, at 2:02 PM, Douglas Gregor via swift-evolution < > swift-evolution@swift.org> wrote:

    Hello Swift community,
   
    The review of SE-0023"API Design Guidelines" begins now and runs through January 31, 2016. The proposal is
    available here:
   
        https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md
   
    Reviews are an important part of the Swift evolution process. All reviews should be sent to the swift-evolution
    mailing list at
   
        https://lists.swift.org/mailman/listinfo/swift-evolution
   
    or, if you would like to keep your feedback private, directly to the review manager. When replying, please try
    to keep the proposal link at the top of the message:
   
        Proposal link:
       
            https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md
       
        Reply text
       
            Other replies
       
     What goes into a review?
   
    The goal of the review process is to improve the proposal under review through constructive criticism and,
    eventually, determine the direction of Swift. When writing your review, here are some questions you might want
    to answer in your review:
   
      + What is your evaluation of the proposal?
      + Is the problem being addressed significant enough to warrant a change to Swift?
      + Does this proposal fit well with the feel and direction of Swift?
      + If you have used other languages or libraries with a similar feature, how do you feel that this proposal
        compares to those?
      + How much effort did you put into your review? A glance, a quick reading, or an in-depth study?
   
    More information about the Swift evolution process is available at
   
        https://github.com/apple/swift-evolution/blob/master/process.md
   
    Thank you,
   
    -Doug Gregor
   
    Review Manager
   
    _______________________________________________
    swift-evolution mailing list
    swift-evolution@swift.org
    https://lists.swift.org/mailman/listinfo/swift-evolution

Current: Use imperative verb phrases for mutating methods: x.reverse(), x.sort(), x.tweak() Use noun phrases for
non-mutating methods: x.distanceTo(...), idx.successor() Proposed: Use verb phrases to declare procedural methods,
whether or not they mutate an instance or just produce side effects: x.reverse(), x.sort(), x.tweak(), x.perform(),
x.dispatch(), x.send() Use noun phrases to describe values returned by a functional method: x.distanceTo(y),
index.successor() (This admittedly leaves further issues around other functional methods, for example,
seq.separatedBySequence(seq) and int.strideTo(other: Self, step:Self.Stride), etc. ) I suggest that mutating
methods are just a procedural method (side effect, no return value) vs functional. -- E > On Jan 22, 2016, at 2:02
PM, Douglas Gregor via swift-evolution wrote: > > Hello Swift community, > > The review of SE-0023"API Design
Guidelines" begins now and runs through January 31, 2016. The proposal is available here: > >
https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md > Reviews are an important
part of the Swift evolution process. All reviews should be sent to the swift-evolution mailing list at > >
https://lists.swift.org/mailman/listinfo/swift-evolution > or, if you would like to keep your feedback private,
directly to the review manager. When replying, please try to keep the proposal link at the top of the message: > >
Proposal link: > > https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md > Reply
text > > Other replies > What goes into a review? > > The goal of the review process is to improve the proposal
under review through constructive criticism and, eventually, determine the direction of Swift. When writing your
review, here are some questions you might want to answer in your review: > > What is your evaluation of the
proposal? > Is the problem being addressed significant enough to warrant a change to Swift? > Does this proposal
fit well with the feel and direction of Swift? > If you have used other languages or libraries with a similar
feature, how do you feel that this proposal compares to those? > How much effort did you put into your review? A
glance, a quick reading, or an in-depth study? > More information about the Swift evolution process is available at

> https://github.com/apple/swift-evolution/blob/master/process.md > Thank you, > > -Doug Gregor > > Review

Manager > > _______________________________________________ > swift-evolution mailing list >
swift-evolution@swift.org > https://lists.swift.org/mailman/listinfo/swift-evolution

--
-Dave

We should finish this review as it is, and then have a much smaller
review of your proposed amendments to the guidelines.

···

on Fri Jan 22 2016, Matthew Johnson <swift-evolution@swift.org> wrote:

This review seems like a good time to bring up the proposal regarding
naming conventions for conversion protocols:
Conversion protocol conventions by anandabits · Pull Request #60 · apple/swift-evolution · GitHub
<https://github.com/apple/swift-evolution/pull/60&gt;\. Dave had
mentioned having the standard library team discuss this as part of the
API guidelines:
[swift-evolution] Requesting a team ruling on the next step, please Re: Proposal: conversion protocol naming conventions
<https://lists.swift.org/pipermail/swift-evolution/Week-of-Mon-20151214/002798.html&gt;\.
I’m wondering if the solution for this naming issue should continue as
an independent proposal or be included as part of the the larger API
Design Guidelines proposal.

--
-Dave

+1

-- E

···

On Jan 22, 2016, at 3:34 PM, Matthew Johnson via swift-evolution <swift-evolution@swift.org> wrote:

This review seems like a good time to bring up the proposal regarding naming conventions for conversion protocols: https://github.com/apple/swift-evolution/pull/60\. Dave had mentioned having the standard library team discuss this as part of the API guidelines: https://lists.swift.org/pipermail/swift-evolution/Week-of-Mon-20151214/002798.html\. I’m wondering if the solution for this naming issue should continue as an independent proposal or be included as part of the the larger API Design Guidelines proposal.

-Matthew

On Jan 22, 2016, at 3:02 PM, Douglas Gregor <dgregor@apple.com <mailto:dgregor@apple.com>> wrote:

Hello Swift community,

The review of SE-0023"API Design Guidelines" begins now and runs through January 31, 2016. The proposal is available here:

https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md
Reviews are an important part of the Swift evolution process. All reviews should be sent to the swift-evolution mailing list at

https://lists.swift.org/mailman/listinfo/swift-evolution
or, if you would like to keep your feedback private, directly to the review manager. When replying, please try to keep the proposal link at the top of the message:

Proposal link:

https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md
Reply text

Other replies
<GitHub - apple/swift-evolution: This maintains proposals for changes and user-visible enhancements to the Swift Programming Language. goes into a review?

The goal of the review process is to improve the proposal under review through constructive criticism and, eventually, determine the direction of Swift. When writing your review, here are some questions you might want to answer in your review:

What is your evaluation of the proposal?
Is the problem being addressed significant enough to warrant a change to Swift?
Does this proposal fit well with the feel and direction of Swift?
If you have used other languages or libraries with a similar feature, how do you feel that this proposal compares to those?
How much effort did you put into your review? A glance, a quick reading, or an in-depth study?
More information about the Swift evolution process is available at

https://github.com/apple/swift-evolution/blob/master/process.md
Thank you,

-Doug Gregor

Review Manager

_______________________________________________
swift-evolution-announce mailing list
swift-evolution-announce@swift.org <mailto:swift-evolution-announce@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution-announce

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution

Swift could use “after” as a prefix, or something similar.

array.sort()
array.afterSort()

I was tempted to say “afterSorting()” but that has the same problems mentioned above.

Jeff Kelley

SlaunchaMan@gmail.com | @SlaunchaMan <https://twitter.com/SlaunchaMan&gt; | jeffkelley.org <http://jeffkelley.org/&gt;

···

On Jan 22, 2016, at 4:53 PM, Joe Groff via swift-evolution <swift-evolution@swift.org> wrote:

How do you handle naming non-mutating versions of these operations? Conjugating other irregular verbs also imposes a barrier on developers whose first language is not English.

Text is not enough to represent whether function are adjectives or verbs. By distinguishing between adjectives (nonmutating) and verbs (mutating) functions, with metadata, we will also be able to settle when to enforce self.

When a function is a mutating verb (i.e. when self. really means “self, "), self. reads redundantly.
When a function is an adjective (i.e. when self. means “me, "), it doesn’t read well if self. is not used.

sort(…)
self.sorted(…)

append(…)
self.appended(with …)

split(using: …)
self.split(by: …)

cut(…)
self.cut(by: …)

Sometimes, “self.” means “I”, but I don’t believe those cases are relevant to this thread.

···

On Jan 22, 2016, at 4:53 PM, Joe Groff via swift-evolution <swift-evolution@swift.org> wrote:

When a mutating method is described by a verb, name its non-mutating counterpart according to the “ed/ing” rule, e.g. the non-mutating versions of x.sort() and x.append(y) are x.sorted() and x.appending(y).

This is a nice rule in theory, but English fights it with the full fury of its irregularity. There are a lot of common operations whose past tense shares a spelling with the infinitive—'split', 'cut', 'read', and 'cast' immediately come to mind. How do you handle naming non-mutating versions of these operations? Conjugating other irregular verbs also imposes a barrier on developers whose first language is not English.

-Joe
_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

Under "Follow case conventions", how should acronyms (like "HTML") be handled: HTMLElement or HtmlElement?

I would certainly prefer the second style. Unless the acronym comes at the end of the identifier, it is more readable when only the first letter of the acronym is uppercase, IMO. Otherwise the acronym merges with the capitalized first letter of the following word.

Using all caps for acronyms also doesn’t work very well at the start of a variable name, leading to:

var hTMLElement = HTMLElement()

versus:

var htmlElement = HtmlElement()

--CK

···

On Jan 22, 2016, at 3:59 PM, Trent Nadeau via swift-evolution <swift-evolution@swift.org> wrote:

On Fri, Jan 22, 2016 at 4:02 PM, Douglas Gregor via swift-evolution <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:
Hello Swift community,

The review of SE-0023"API Design Guidelines" begins now and runs through January 31, 2016. The proposal is available here:

https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md
Reviews are an important part of the Swift evolution process. All reviews should be sent to the swift-evolution mailing list at

https://lists.swift.org/mailman/listinfo/swift-evolution
or, if you would like to keep your feedback private, directly to the review manager. When replying, please try to keep the proposal link at the top of the message:

Proposal link:

https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md
Reply text

Other replies
<GitHub - apple/swift-evolution: This maintains proposals for changes and user-visible enhancements to the Swift Programming Language. goes into a review?

The goal of the review process is to improve the proposal under review through constructive criticism and, eventually, determine the direction of Swift. When writing your review, here are some questions you might want to answer in your review:

What is your evaluation of the proposal?
Is the problem being addressed significant enough to warrant a change to Swift?
Does this proposal fit well with the feel and direction of Swift?
If you have used other languages or libraries with a similar feature, how do you feel that this proposal compares to those?
How much effort did you put into your review? A glance, a quick reading, or an in-depth study?
More information about the Swift evolution process is available at

https://github.com/apple/swift-evolution/blob/master/process.md
Thank you,

-Doug Gregor

Review Manager

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution

--
Trent Nadeau
_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

How would we apply this to delegate patterns?
For example, would we keep tableview(tableView:cellForRowAtIndexPath:), or
would we switch to delegate(tableView:cellForRowAtIndexPath:) ?
Or perhaps better, for clarity over which protocol is being conformed to /
which property of the delegator is calling the function:
dataSource(tableView:cellForRowAtIndexPath:),
delegate(tableView:didSelectRowAtIndexPath:)

···

On Sat, Jan 23, 2016 at 12:00 AM, David Owens II via swift-evolution < swift-evolution@swift.org> wrote:

*Compensate For Weak Type Information as needed to clarify a
parameter’s role.*

Especially when a parameter type is NSObject, Any, AnyObject, or a
fundamental type such Int or String, type information and context at
the point of use may not fully convey intent. In this example, the
declaration may be clear, but the use site is vague:

func add(observer: NSObject, for keyPath: String)
grid.add(self, for: graphics) // vague

To restore clarity, precede each weakly-typed parameter with a noun
describing its role:

func addObserver(_ observer: NSObject, forKeyPath path: String)
grid.addObserver(self, forKeyPath: graphics) // clear

I don’t understand why to compensate for weak type information we put some
of that compensation in the name of the function and other parts of it in
the [external] name of the parameter.

If we were going to reference functions like this: addObserver:forKeyPath,
then I can understand it. But that’s not the plan of record, it’s to do
this: addObserver(_:forKeyPath).

Regardless of the default naming scheme, it seems like the rule should be
to use external names to clarify that parameters role.

func add(observer observer: NSObject, forKeyPath path: String)
grid.add(observer: self, forKeyPath: graphics)

This promotes a very clear and consistent rule: weak type information
should be clarified by the parameter’s external name. There are no
exceptions for the first parameter. Otherwise, it seems like there is super
fine line between this rule and the next one below.

Additionally, this also alleviates my concerns with the default parameter
have _ as the external name by default because this addresses the case
when it would be desirable to have that name. Further, the case below
handles the case when it’s not.

*Omit Needless Words. Every word in a name should convey salient
information at the use site.*

More words may be needed to clarify intent or disambiguate meaning, but
those that are redundant with information the reader already
possesses should be omitted. In particular, omit words that merely repeat
type information:

public mutating func removeElement(member: Element) -> Element?
allViews.removeElement(cancelButton)

In this case, the word Element adds nothing salient at the call site. This
API would be better:

public mutating func remove(member: Element) -> Element?
allViews.remove(cancelButton) // clearer

Occasionally, repeating type information is necessary to avoid ambiguity,
but in general it is better to use a word that describes a
parameter’s role rather than its type. See the next item for details.

The description here seems to overlap with the “Compensate for Weak Type
Information” rule, especially with the clause: “repeating type
information”. It may be better to re-work the example to be
`removeItem(member: Element)` to make this distinction more clear that it’s
not type information being removed.

Also, by clarifying that statement, the above rule change I suggested
would be consistent. Type information clarification goes into the external
parameter name, functionality clarification goes into the function name.
Those are hard-n-fast rules that are straight-forward.

*Be Grammatical*

When a mutating method is described by a verb, name its non-mutating
counterpart according to the “ed/ing” rule, e.g. the non-mutating versions
of x.sort() and x.append(y) are x.sorted() and x.appending(y).

Is this guideline suggesting that we should design our APIs to generally
have both mutating and non-mutaging counterparts?

As other have pointed out, this is also very hard to do all the time. I
think the alternatives are worse. It would be nice if there were a way to
annotate all member functions as mutating/non-mutating to really by-pass
this ambiguity.

Other than the above, the proposal looks pretty good to me.

-David

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

I agree. It would make enum cases feel more consistent with the rest of the language to make them lowerCamelCase.

-Joe

···

On Jan 23, 2016, at 2:12 AM, Marc Knaup via swift-evolution <swift-evolution@swift.org> wrote:

What is the rationale behind naming enumeration cases in upper camel case?

Follow case conventions: names of types, protocols and enum cases areUpperCamelCase. Everything else is lowerCamelCase.

let a = NSComparisonResult.OrderedSame // refers to a value, but is upper-case
let b = NSDate.distantFuture // refers to a property/value, but is lower-case
everything related to types (type names, protocol names, generic type parameter names) should be upper camel case
everything else (function names, property names, variable names, etc.) should be lower camel case
This is already the current and the proposed recommendation with enumeration cases being the only exception.
Enumeration cases are not types.

FWIW, I don't think that we have a defensible rationale, and feel
strongly that we should change this. Of course, it's not up to me
alone...

···

on Sat Jan 23 2016, Marc Knaup <swift-evolution@swift.org> wrote:

Proposal link: https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md

What is the rationale behind naming enumeration cases in upper camel case?

*Follow case conventions:* names of types, protocols and enum cases are

UpperCamelCase. Everything else is lowerCamelCase.

let a = NSComparisonResult.OrderedSame // refers to a value, but is upper-case
let b = NSDate.distantFuture // refers to a property/value, but is lower-case

   - everything related to types (type names, protocol names, generic type
   parameter names) should be upper camel case
   - everything else (function names, property names, variable names, etc.)
   should be lower camel case

This is already the current and the proposed recommendation with
enumeration cases being the only exception.
Enumeration cases are not types.

--
-Dave

Compensate For Weak Type Information as needed to clarify a parameter’s role.

Especially when a parameter type is NSObject, Any, AnyObject, or a
fundamental type such Int or String, type information and context at
the point of use may not fully convey intent. In this example, the
declaration may be clear, but the use site is vague:

func add(observer: NSObject, for keyPath: String)
grid.add(self, for: graphics) // vague

To restore clarity, precede each weakly-typed parameter with a noun describing its role:

func addObserver(_ observer: NSObject, forKeyPath path: String)
grid.addObserver(self, forKeyPath: graphics) // clear

I don’t understand why to compensate for weak type information we put
some of that compensation in the name of the function and other parts
of it in the [external] name of the parameter.

IIUC, some people feel strongly that it would be really strange and
nonuniform to have a substantial fraction of methods with an argument
label on the first argument unless that percentage was nearly 100.

[I don't know whether there's an "official terminology" for these names,
but we've been calling them "argument labels" in the naming discussions.
Note that the ("internal") parameter names aren't strictly internal as
they get used in documentation comments, and should be chosen
accordingly. So, I'm using the terms "argument label" and "parameter
name".]

If we were going to reference functions like this:
addObserver:forKeyPath, then I can understand it. But that’s not the
plan of record, it’s to do this: addObserver(_:forKeyPath).

That's an interesting argument.

Regardless of the default naming scheme, it seems like the rule should
be to use external names to clarify that parameters role.

func add(observer observer: NSObject, forKeyPath path: String)
grid.add(observer: self, forKeyPath: graphics)

This promotes a very clear and consistent rule: weak type information
should be clarified by the parameter’s external name. There are no
exceptions for the first parameter.

That seems very clean to me.

Otherwise, it seems like there is super fine line between this rule
and the next one below.

Additionally, this also alleviates my concerns with the default
parameter have _ as the external name by default because this
addresses the case when it would be desirable to have that
name.

Sorry, I don't understand what you're getting at here.

Further, the case below handles the case when it’s not.

Omit Needless Words. Every word in a name should convey salient information at the use site.

More words may be needed to clarify intent or disambiguate meaning,
but those that are redundant with information the reader already
possesses should be omitted. In particular, omit words that merely
repeat type information:

public mutating func removeElement(member: Element) -> Element?
allViews.removeElement(cancelButton)

In this case, the word Element adds nothing salient at the call site. This API would be better:

public mutating func remove(member: Element) -> Element?
allViews.remove(cancelButton) // clearer

Occasionally, repeating type information is necessary to avoid
ambiguity, but in general it is better to use a word that describes
a parameter’s role rather than its type. See the next item for
details.

The description here seems to overlap with the “Compensate for Weak
Type Information” rule, especially with the clause: “repeating type
information”. It may be better to re-work the example to be
`removeItem(member: Element)` to make this distinction more clear that
it’s not type information being removed.

Oh, great point!

Also, by clarifying that statement, the above rule change I suggested
would be consistent. Type information clarification goes into the
external parameter name, functionality clarification goes into the
function name. Those are hard-n-fast rules that are straight-forward.

I like 'em, FWIW.

Be Grammatical

When a mutating method is described by a verb, name its non-mutating
counterpart according to the “ed/ing” rule, e.g. the non-mutating
versions of x.sort() and x.append(y) are x.sorted() and
x.appending(y).

Is this guideline suggesting that we should design our APIs to
generally have both mutating and non-mutaging counterparts?

Definitely not.

As other have pointed out, this is also very hard to do all the
time. I think the alternatives are worse.

The alternatives to always creating mutating/nonmutating pairs? What
alternatives have you considered, and what do you see the consequences
to be?

It would be nice if there were a way to annotate all member functions
as mutating/non-mutating to really by-pass this ambiguity.

I don't know what you mean by that. Can you explain?

FWIW, there are potential language-level approaches to this problem
(e.g. https://github.com/apple/swift/blob/master/docs/proposals/Inplace.rst\),
but in the absence of language features, it's something we need a
convention for.

···

on Fri Jan 22 2016, David Owens II <swift-evolution@swift.org> wrote:

--
-Dave

*Protocols* that describe what something *is* should read as nouns

(e.g. |Collection|). Protocols that describe a *capability* should be
named using the suffixes |able|, |ible|, or |ing| (e.g. |Equatable|,
>ProgressReporting>).

I personally like the idea behind the current convention for protocols
that describe a thing (IntegerType, CollectionType, etc) where there is
a suffix of Type appended to the end, so I give this specific part of
the proposal a -1.

For some people, that convention made no sense at all, no matter how
many times I explained the rationale: they would always come back to,
“but that's a protocol, not a type, so ending its name with Type makes
no sense.” At some point, empirical evidence of people's cognitive
dissonance outweighs nice theories, and I had to admit that it wasn't
working for people overall.

(That assessment was from a small sample, and if nobody in the community
feels the same way, that would be significant news.)

The specific wording of the protocol's name is not so important as the
recognition at a glance that this is a protocol vs a concrete type. I
like being able to infer at a glance how I'm expected to use a
specific type reference based on its name alone; otherwise I may have
to refer back to the type definition to refresh my memory of whether
or not it is in fact a protocol or is something else.

That was part of the original motivation. One issue with that is that
protocols without Self requirements or associated types *are* concrete
types, so it weakens the argument for making a strong distinction.

The other thing, is, I wonder how much of that warm fuzzy feeling we get
from being able to know at a glance it's a protocol is actually useful
in programming or maintenance. After we made the changes in the
standard library I was quite pleased by what IMO was the resulting
improvement in readability. I ask that you take a look at the effect
this has on actual code.

From the standard library,

Comparing main...swift-3-api-guidelines · apple/swift · GitHub has a few
of these. You might try this on your own project.

This change could also lead to confusion among some developers. For
someone who is new to Swift, would they know they should use Bool over
Boolean if they've seen both types before? Both names look reasonable to
store a boolean value, but the semantics of each type differ
significantly.

Well, yeah. BooleanType should be retired; if we didn't know that was
in the plan, we'd have renamed it to BooleanProtocol or TruthValue or
somthing.

Someone may try to have a type conform to Bool instead of Boolean,
which would obviously not work, but could cause some consternation for
developers who don't know the difference by heart. Naming the
protocol BooleanType at least calls out that this may not be
conceptually the same as a plain boolean value, which could make a
developer think twice before trying to use that over Bool.

Removing some common prefix

suffix?

from these kinds of protocols could also run the risk of
unintentionally shadowing type names, if someone wanted to write their
own Collection or Error struct or class for instance, or if a
pre-existing concrete type in their code turned out to unexpectedly
shadow a protocol in a new dependency that they want to add. These
situations would not cause any technical hiccups due to module
namespacing, but it could lead to confusion when a developer forgets
to qualify the name and tries to use one type where the other is
expected.

Yes, but shadowing surprises are a fact of life whether we make this
change or not.

In short, appending Type (or something like it) i think is a reasonable
convention to keep around for non-behavioral protocols.

As far as alternatives to 'Type', I personally don't like the suffix
'Protocol' as much (which is suggested as a disambiguation option in the
related standard library review), since 'Type' is shorter, feels nicer
to read, and describes the purpose of the protocol well to me. C#'s
approach of prefixing all interfaces with a capital I would be even more
succinct, but I personally don't think that approach would look nice to
read either. (PCollection, PBoolean? Ick.)

Ick indeed.

···

on Fri Jan 22 2016, Kevin Lundberg <swift-evolution@swift.org> wrote:

--
-Dave

I think it makes sense for enum cases to be UpperCamelCase as they can be
thought of as scoped types (singleton types in the case of cases with no
associated types).

Option set elements, on the other hand, I think really are values so it may
make sense for those to be lowerCamelCase.

···

On Sat, Jan 23, 2016 at 1:11 PM, Joe Groff via swift-evolution < swift-evolution@swift.org> wrote:

On Jan 23, 2016, at 2:12 AM, Marc Knaup via swift-evolution < > swift-evolution@swift.org> wrote:

What is the rationale behind naming enumeration cases in upper camel case?

*Follow case conventions:* names of types, protocols and enum cases are

UpperCamelCase. Everything else is lowerCamelCase.

let a = NSComparisonResult.OrderedSame // refers to a value, but is
upper-case
let b = NSDate.distantFuture // refers to a property/value, but
is lower-case

   - everything related to types (type names, protocol names, generic
   type parameter names) should be upper camel case
   - everything else (function names, property names, variable names,
   etc.) should be lower camel case

This is already the current and the proposed recommendation with
enumeration cases being the only exception.
Enumeration cases are not types.

I agree. It would make enum cases feel more consistent with the rest of
the language to make them lowerCamelCase.

-Joe

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

--
Trent Nadeau

I never liked the convention of distinguishing between interfaces and classes by prepending an „I“ for interfaces in other languages and I’m not overly fond fond of the suffix „Type“ currently used in Swift protocols.
This is the same as prefixing (or suffixing) variable names with something to express their type, e.g. `String sName` or `int iLength`.
That’s what we have type information for.

And because of the substitution principle it should make no difference whether I have a protocol or a struct or class. What is a `CollectionType` vs. a `Collection`? Is it the type of a `Collection`, i.e. a meta type? Why not simply `Collection` if it describes what a collection is?
I guess its often more the problem of finding a suitable different name for the implementation and that’s why I sometimes wonder whether it might make sense to give protocols their own namespace…

In short, I am not fond of the suffix „Type“ (but I would dislike the suffix „Protocol“ or prefixes like „I“ or „P“ even more).

I’m open to debate, though :-)

-Thorsten

···

Am 23.01.2016 um 06:25 schrieb Kevin Lundberg via swift-evolution <swift-evolution@swift.org>:

> Protocols that describe what something is should read as nouns (e.g. Collection). Protocols that describe a capability should be named using the suffixes able, ible, or ing (e.g. Equatable, ProgressReporting).

I personally like the idea behind the current convention for protocols that describe a thing (IntegerType, CollectionType, etc) where there is a suffix of Type appended to the end, so I give this specific part of the proposal a -1. The specific wording of the protocol's name is not so important as the recognition at a glance that this is a protocol vs a concrete type. I like being able to infer at a glance how I'm expected to use a specific type reference based on its name alone; otherwise I may have to refer back to the type definition to refresh my memory of whether or not it is in fact a protocol or is something else.

This change could also lead to confusion among some developers. For someone who is new to Swift, would they know they should use Bool over Boolean if they've seen both types before? Both names look reasonable to store a boolean value, but the semantics of each type differ significantly. Someone may try to have a type conform to Bool instead of Boolean, which would obviously not work, but could cause some consternation for developers who don't know the difference by heart. Naming the protocol BooleanType at least calls out that this may not be conceptually the same as a plain boolean value, which could make a developer think twice before trying to use that over Bool.

Removing some common prefix from these kinds of protocols could also run the risk of unintentionally shadowing type names, if someone wanted to write their own Collection or Error struct or class for instance, or if a pre-existing concrete type in their code turned out to unexpectedly shadow a protocol in a new dependency that they want to add. These situations would not cause any technical hiccups due to module namespacing, but it could lead to confusion when a developer forgets to qualify the name and tries to use one type where the other is expected.

In short, appending Type (or something like it) i think is a reasonable convention to keep around for non-behavioral protocols.

As far as alternatives to 'Type', I personally don't like the suffix 'Protocol' as much (which is suggested as a disambiguation option in the related standard library review), since 'Type' is shorter, feels nicer to read, and describes the purpose of the protocol well to me. C#'s approach of prefixing all interfaces with a capital I would be even more succinct, but I personally don't think that approach would look nice to read either. (PCollection, PBoolean? Ick.)
_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

API guidelines should probably be consistent about enum cases and static let properties

I’ve been naming my 'static let’s in UpperCamelCase to match the convention of enums, because I often use them the same way in code. But standard types do differently, e.g.

var initialPoint:CGPoint = .zero

-DW

···

On Jan 23, 2016, at 11:11 AM, Joe Groff via swift-evolution <swift-evolution@swift.org> wrote:

On Jan 23, 2016, at 2:12 AM, Marc Knaup via swift-evolution <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:

What is the rationale behind naming enumeration cases in upper camel case?

Follow case conventions: names of types, protocols and enum cases areUpperCamelCase. Everything else islowerCamelCase.

let a = NSComparisonResult.OrderedSame // refers to a value, but is upper-case
let b = NSDate.distantFuture // refers to a property/value, but is lower-case
everything related to types (type names, protocol names, generic type parameter names) should be upper camel case
everything else (function names, property names, variable names, etc.) should be lower camel case
This is already the current and the proposed recommendation with enumeration cases being the only exception.
Enumeration cases are not types.

I agree. It would make enum cases feel more consistent with the rest of the language to make them lowerCamelCase.

-Joe

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution

Hello Swift community,

The review of SE-0023"API Design Guidelines" begins now and runs
through January 31, 2016. The proposal is available here:

https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md

FYI, a number of minor changes were made to the development version of
the guidelines at
http://apple.github.io/swift-internals/api-design-guidelines/ that may
make it easier for you to evaluate:

* When the page is printed, all sections are always shown expanded.

Thank you for this. Can you extend this practice to all Apple documentation please?

* A button was added to the top of the page that expands or collapses
all details sections.

Another big thanks.

···

On Jan 23, 2016, at 10:49 AM, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:
on Fri Jan 22 2016, Douglas Gregor <swift-evolution@swift.org> wrote:

* Presentation tweaks were made to:
* Help the color-impaired interpret code examples
* Omit needless graphical clutter.

* A series of copyedits by our editorial department were applied. These
are mostly "gardening," as @practicalswift would put it; they
eliminate inconsistencies and bring it "up to code" w.r.t. Apple
editorial practices.

No substantial changes were made to any of the content, so this version
should be a suitable substitute for
Swift.org - API Design Guidelines for the purposes
of the review.

Cheers,

--
-Dave

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

I think Joe's reply is a pretty good summary.

At a high-level, I really get no sense on how APIs are really supposed to be developed in Swift. Joe talks about second arguments generally becoming prepositional phrases, but is that the true intent? Because that's not what the guideline says, nor what the language semantics really promote or suggest to do.

For example, the guidelines say to do one thing but the example does something different:

Compensate For Weak Type Information as needed to clarify a parameter’s role.

Especially when a parameter type is NSObject, Any, AnyObject, or a fundamental type such Int or String, type information and context at the point of use may not fully convey intent. In this example, the declaration may be clear, but the use site is vague:

func add(observer: NSObject, for keyPath: String)
grid.add(self, for: graphics)

To restore clarity, precede each weakly-typed parameter with a noun describing its role:

func addObserver(_ observer: NSObject, forKeyPath path: String)
grid.addObserver(self, forKeyPath: graphics) // clear

This example already had a "for" in the label, but if it were not already there, the API, according to the guidelines, should become this:

func addObserver(_ observer: NSObject, keyPath path: String)
grid.addObserver(self, keyPath: graphics) // clear

Especially when compared with the ObjC import items. Seemingly, the ObjC APIs would be using prepositional clauses for parameter labels while the Swift labels would simply be more descriptive nouns.

The rules I described are keeping in strict guidance to the API design guidelines of adding nouns. So the above would actually be:

func add(observer o: NSObject, keyPath path: String)
grid.add(observer: self, keyPath: graphics)

However, if the API guidelines are really about creating APIs that are to be read in a more English-like manner, like ObjC APIs are designed, then the guidelines should really be amended to make that clear.

If the intention is truly that Swift APIs are supposed to read as naturally as ObjC APIs, then I completely agree with Joe that there should be a language change to actually require the label for parameters.

func addObserver(o: NSObject, path: String) // error: Argument label required for `path`.

However, this pattern of using prepositional phrases is still going to be in contradiction when using init().

let items = Array<Int>(capacityOf: 12, filledWith: 10)

// vs

let items = Array<Int>(count: 12, repeatedValue: 10)

The difference is that init has a much tighter coupling with direct sets to properties on the type.

So yeah... basic story is, even after using Swift since its been released, I still have no clear sense of what a Swift API should look like, and the guidelines don't bring any of that clarity that I'm missing to the table. At the end of the day, Swift chose a C-style pattern which actively dissuades API authors from building the more fluid types of APIs we have in ObjC; there's simply more sigils in the way to break up a natural reading of the API.

grid.addObserver(self, forKeyPath: graphics)

// vs

[grid addObserver:self forKeyPath:graphics]

All of my inclinations for C-style syntactical languages say the API should be (in order of my conceptual preference model):

grid.add(observer: self, keyPath: graphics)

// or

grid.addObserver(self, keyPath: graphics)

// or

grid.addObserver(self, graphics)

And then take this proposed change to a Swift based on guideline updates:

extension Strideable {

- public func stride(through end: Self, by stride: Stride) -> StrideThrough<Self>
+ public func strideThrough(end: Self, by stride: Stride) -> StrideThrough<Self>

}

In what part of the guidelines does it say that we should "by" as the argument label? The stride parameter does not have a lack of type information; in fact, it's quite strong. The call site *is* arguably better with "by" vs. "stride". However, "stride" is not missing context on type information or role specificity.

I guess I'm starting to ramble on here, so I'll stop now...

-David

···

On Jan 23, 2016, at 10:45 AM, Joe Groff <jgroff@apple.com> wrote:

This all looks good to me (aside from the linguistic problems with verb conjugation I've raised in another subthread). However, I think these naming guidelines lead us to reconsider our default argument labeling rules for 'func' declarations again, as David Owens and others have suggested. The stated goal of the current language rule is to guide people into good API design following our conventions, but I don't think it succeeds in serving that purpose. If you follow the guidelines, the argument labels for your secondary arguments generally end up becoming prepositional phrases, which make for poor variable names, and you're naturally guided to giving the argument an explicit descriptive binding name:

func perform(stuff: Stuff, with: Thing) {
  with.apply(stuff) // 'with' is a weird variable name
}

func perform(stuff: Stuff, with thing: Thing) {
  thing.apply(stuff) // 'thing' is better
}

The shorthand thus doesn't save the good API citizen from much work. On the other hand, a developer who's unaware or uninterested in the guidelines and is just trying to C or Java in Swift gets argument labels by default that neither follow the guidelines nor meet their expectation:

func atan2(y: Double, x: Double) -> Double { ... }

atan2(10, 10) // Why doesn't this work?
atan2(10, x: 10) // Nobody wants this

And when staring down potentially dozens or hundreds of compile errors at various mismatched use sites, they're unlikely to reconsider their API naming choice, and will instead do the minimal amount of work to get their code to compile by suppressing the argument label. The language hasn't led this developer to better conventional API design either.

I can think of a couple possible modifications to the language rule that could help reduce the surprise factor, and still lead people to good API design:

- Require all 'func' arguments after the first to explicitly specify both a label and a binding name. Users following the guidelines will usually end up doing this anyway, and users who aren't will get a helpful message instead of unexpected behavior. This also avoids a problem with our current rule, where otherwise identical-looking parameter declarations in a 'func' end up behaving differently based on position. A diagnostic immediately at the declaration site also seems more likely to me to lead the developer to think more about their API naming; diagnosing call sites that don't look the way they want is just going to lead them to reactively suppress the labels to get their code to compile.
- Change the default rule so that all arguments *after an explicitly labeled argument* default to being labeled (instead of all arguments after the first). It's unlikely anyone wants an unlabeled argument positionally after a labeled one, and the rare methods in Cocoa that take more than two arguments do tend to use noun rather than preposition phrases for arguments after the second. Users following the guidelines get nice labeled APIs, and users who aren't get the bare, uncaring anonymous arguments they deserve:

func perform(stuff: Stuff, with thing: Thing, options: StuffOptions) // perform(_:with:options:)
func atan2(y: Double, x: Double) // atan2(_:_:)

-Joe

On Jan 22, 2016, at 1:02 PM, Douglas Gregor via swift-evolution <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:

Hello Swift community,

The review of SE-0023"API Design Guidelines" begins now and runs through January 31, 2016. The proposal is available here:

https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md
Reviews are an important part of the Swift evolution process. All reviews should be sent to the swift-evolution mailing list at

https://lists.swift.org/mailman/listinfo/swift-evolution
or, if you would like to keep your feedback private, directly to the review manager. When replying, please try to keep the proposal link at the top of the message:

Proposal link:

https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md
Reply text

Other replies
<GitHub - apple/swift-evolution: This maintains proposals for changes and user-visible enhancements to the Swift Programming Language. goes into a review?

The goal of the review process is to improve the proposal under review through constructive criticism and, eventually, determine the direction of Swift. When writing your review, here are some questions you might want to answer in your review:

What is your evaluation of the proposal?
Is the problem being addressed significant enough to warrant a change to Swift?
Does this proposal fit well with the feel and direction of Swift?
If you have used other languages or libraries with a similar feature, how do you feel that this proposal compares to those?
How much effort did you put into your review? A glance, a quick reading, or an in-depth study?
More information about the Swift evolution process is available at

https://github.com/apple/swift-evolution/blob/master/process.md
Thank you,

-Doug Gregor

Review Manager

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution

What is the rationale behind naming enumeration cases in upper camel case?

Follow case conventions: names of types, protocols and enum cases areUpperCamelCase. Everything else is lowerCamelCase.

let a = NSComparisonResult.OrderedSame // refers to a value, but is upper-case
let b = NSDate.distantFuture // refers to a property/value, but is lower-case
everything related to types (type names, protocol names, generic type parameter names) should be upper camel case
everything else (function names, property names, variable names, etc.) should be lower camel case
This is already the current and the proposed recommendation with enumeration cases being the only exception.
Enumeration cases are not types.

This is something that’s come up a few times before, and I (personally) agree that it makes more sense for enum cases to be lowerCamelCase. Thanks for bringing it up!

  - Doug

···

On Jan 23, 2016, at 2:12 AM, Marc Knaup <marc@knaup.koeln> wrote:

On Fri, Jan 22, 2016 at 10:02 PM, Douglas Gregor via swift-evolution <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:
Hello Swift community,

The review of SE-0023"API Design Guidelines" begins now and runs through January 31, 2016. The proposal is available here:

https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md
Reviews are an important part of the Swift evolution process. All reviews should be sent to the swift-evolution mailing list at

https://lists.swift.org/mailman/listinfo/swift-evolution
or, if you would like to keep your feedback private, directly to the review manager. When replying, please try to keep the proposal link at the top of the message:

Proposal link:

https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md
Reply text

Other replies
<GitHub - apple/swift-evolution: This maintains proposals for changes and user-visible enhancements to the Swift Programming Language. goes into a review?

The goal of the review process is to improve the proposal under review through constructive criticism and, eventually, determine the direction of Swift. When writing your review, here are some questions you might want to answer in your review:

What is your evaluation of the proposal?
Is the problem being addressed significant enough to warrant a change to Swift?
Does this proposal fit well with the feel and direction of Swift?
If you have used other languages or libraries with a similar feature, how do you feel that this proposal compares to those?
How much effort did you put into your review? A glance, a quick reading, or an in-depth study?
More information about the Swift evolution process is available at

https://github.com/apple/swift-evolution/blob/master/process.md
Thank you,

-Doug Gregor

Review Manager

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution

This all looks good to me (aside from the linguistic problems with verb conjugation I've raised in another subthread). However, I think these naming guidelines lead us to reconsider our default argument labeling rules for 'func' declarations again, as David Owens and others have suggested. The stated goal of the current language rule is to guide people into good API design following our conventions, but I don't think it succeeds in serving that purpose. If you follow the guidelines, the argument labels for your secondary arguments generally end up becoming prepositional phrases, which make for poor variable names, and you're naturally guided to giving the argument an explicit descriptive binding name:

func perform(stuff: Stuff, with: Thing) {
  with.apply(stuff) // 'with' is a weird variable name
}

func perform(stuff: Stuff, with thing: Thing) {
  thing.apply(stuff) // 'thing' is better
}

I don’t understand how you came to the conclusion that secondary arguments generally end up becoming prepositional phrases. I know you’re using abstract examples, but the “with” in your example above is essentially vacuous. Indeed, the Clang importer rules of SE-0005 won’t allow us to prune argument labels if the result is just “with” (or “for”, or one of a few other vacuous words). I would expect the API above to use:

  func perform(stuff: Stuff, thing: Thing) {

Now, meaningful prepositions do show up sometimes as the argument label. For example

  func insert(x: Element, at index: Index)

but this case doesn’t seem like the dominant case it all: you’re often just describing what the argument is rather than its relationship to the operation, and it only can be “just a preposition” if any word you add to clarify the role of the parameter would be redundant with the type information.

The shorthand thus doesn't save the good API citizen from much work. On the other hand, a developer who's unaware or uninterested in the guidelines and is just trying to C or Java in Swift gets argument labels by default that neither follow the guidelines nor meet their expectation:

func atan2(y: Double, x: Double) -> Double { ... }

atan2(10, 10) // Why doesn't this work?
atan2(10, x: 10) // Nobody wants this

And when staring down potentially dozens or hundreds of compile errors at various mismatched use sites, they're unlikely to reconsider their API naming choice, and will instead do the minimal amount of work to get their code to compile by suppressing the argument label.

*Any* refactoring tool for Swift should be able to handle renaming argument labels, so this shouldn’t be any more painful that your typical rename.

The language hasn't led this developer to better conventional API design either.

I can think of a couple possible modifications to the language rule that could help reduce the surprise factor, and still lead people to good API design:

- Require all 'func' arguments after the first to explicitly specify both a label and a binding name. Users following the guidelines will usually end up doing this anyway, and users who aren't will get a helpful message instead of unexpected behavior. This also avoids a problem with our current rule, where otherwise identical-looking parameter declarations in a 'func' end up behaving differently based on position. A diagnostic immediately at the declaration site also seems more likely to me to lead the developer to think more about their API naming; diagnosing call sites that don't look the way they want is just going to lead them to reactively suppress the labels to get their code to compile.

Obviously, I’d be concerned about us introducing a significant amount of boilerplate by doing this. We could determine just how much boilerplate this would be added by proxy: how many second-or-later parameters in Objective-C methods have the same identifier as the corresponding selector piece? If it’s a significant fraction, then this kind of change becomes hard to justify.

- Change the default rule so that all arguments *after an explicitly labeled argument* default to being labeled (instead of all arguments after the first). It's unlikely anyone wants an unlabeled argument positionally after a labeled one, and the rare methods in Cocoa that take more than two arguments do tend to use noun rather than preposition phrases for arguments after the second. Users following the guidelines get nice labeled APIs, and users who aren't get the bare, uncaring anonymous arguments they deserve:

func perform(stuff: Stuff, with thing: Thing, options: StuffOptions) // perform(_:with:options:)
func atan2(y: Double, x: Double) // atan2(_:_:)

It seems to me that this nudges us toward less-readable call sites, with anonymous arguments dominating simply because it’s the easy thing. It’s more motivating to fix a poor API decision (i.e., a bad argument label) if you’re seeing it at each and every call site...

  - Doug

···

On Jan 23, 2016, at 10:45 AM, Joe Groff <jgroff@apple.com> wrote:

-Joe

On Jan 22, 2016, at 1:02 PM, Douglas Gregor via swift-evolution <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:

Hello Swift community,

The review of SE-0023"API Design Guidelines" begins now and runs through January 31, 2016. The proposal is available here:

https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md
Reviews are an important part of the Swift evolution process. All reviews should be sent to the swift-evolution mailing list at

https://lists.swift.org/mailman/listinfo/swift-evolution
or, if you would like to keep your feedback private, directly to the review manager. When replying, please try to keep the proposal link at the top of the message:

Proposal link:

https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md
Reply text

Other replies
<GitHub - apple/swift-evolution: This maintains proposals for changes and user-visible enhancements to the Swift Programming Language. goes into a review?

The goal of the review process is to improve the proposal under review through constructive criticism and, eventually, determine the direction of Swift. When writing your review, here are some questions you might want to answer in your review:

What is your evaluation of the proposal?
Is the problem being addressed significant enough to warrant a change to Swift?
Does this proposal fit well with the feel and direction of Swift?
If you have used other languages or libraries with a similar feature, how do you feel that this proposal compares to those?
How much effort did you put into your review? A glance, a quick reading, or an in-depth study?
More information about the Swift evolution process is available at

https://github.com/apple/swift-evolution/blob/master/process.md
Thank you,

-Doug Gregor

Review Manager

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution