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

[Dave Abrahams]

on Fri Jan 29 2016, Paul Cantrell <swift-evolution at swift.org> wrote:

> I took Adriano’s comments not as a specific syntax proposal — clearly
> Ruby’s use of the ? and ! symbols is both different from and
> fundamentally incompatible with Swift’s — but rather as a way of
> pointing out that another language has solved this problem by
> reserving a special notation for “mutating” instead of trying to pack
> it in to grammar-based or otherwise natural-langue-based conventions,
> and that worked out all right.

Yes, I understand that.  But language features to support such a special
notation are really off the table for Swift 3, so we're left with
“grammar-based or otherwise natural-langue-based conventions,” and
discussion of anything else is not relevant to this review.

> Turning back to the guidelines review at hand, I do worry that these
> proposed guidelines pack too much significance into the vagaries of
> English grammar, which (as we’ve found out on this thread) is an
> inconsistent and fickle friend. I’m personally in favor of charging
> ahead with that quixotic venture nonetheless, but I do worry a bit
> that the guidelines as stated are too narrowly stated in all the
> places where grammar is involved.

Understood.  It would be nice to be able to say “just do what makes
sense,” but the downside is that you lose regularity and you lose
developer hours agonizing over trivia.  The downside of API guidelines
is that they restrain you from doing what you want to do... and the
upside is that they restain you from doing whatever you want to do. ;-)

> Cheers, P
>
>> On Jan 29, 2016, at 2:55 PM, David Waite via swift-evolution
>> <swift-evolution at swift.org> wrote:
>> 
>> In Ruby ‘?’ indicates conditional usage while in Swift ‘?’ indicates
>> optionality or an optional (fall-back) execution path (this
>> operation returned return nil as a fallback for not holding a value,
>> method being called on a nil value, method call throwing an error,
>> etc)
>> 
>> This is why in Ruby 2.3, the “?.” operator that they wanted to use
>> eventually evolved into an “&.” operator.
>> 
>> ‘!’ in Ruby means either this operation is destructive or that this
>> operation will raise an exception on error, in Swift it means as a
>> general rule ‘failures are precondition failures which will crash
>> your application’
>> 
>> -DW
>> 
>>> On Jan 29, 2016, at 11:10 AM, Adriano Ferreira via swift-evolution
>>> <swift-evolution at swift.org
>>> <mailto:swift-evolution at swift.org>>
>>> wrote:
>>> 
>>> Indeed, Ruby has an interesting convention where a question mark
>>> (?) is used for boolean functions/methods:
>>> 
>>> In Swift: foo.contains(...)
>>> In Ruby: foo.include?(...)
>>> 
>>> In Swift: foo.isEmpty
>>> In Ruby: foo.empty?
>>> 
>>> Well, in the last case `isEmpty` is a property whereas `empty?` is a method, but the idea is similar.
>>> 
>>> 
>>> Also, an exclamation mark (!) is generally used to indicate that a function/method mutates `self`:
>>> 
>>> Non-mutating:
>>> 
>>> Swift — foo.reverse()
>>> Ruby — foo.reverse
>>> 
>>> Mutating:
>>> 
>>> Swift — foo.reverseInPlace()
>>> Ruby — foo.reverse!
>>> 
>>> 
>>> Non-mutating:
>>> 
>>> Swift — foo.sort()  or  foo.sort({…})
>>> Ruby — foo.sort  or  foo.sort {…}
>>> 
>>> Mutating:
>>> 
>>> Swift — foo.sortInPlace()  or  foo.sortInPlace({…})
>>> Ruby — foo.sort!  or  foo.sort! {…} 
>>> 
>>> 
>>> I think it’s a simple and nice way of addressing the naming issue
>>> of mutating vs. non-mutating or pure vs. impure
>>> functions/methods. However, this conflicts with the syntax sugar of
>>> Optionals and, therefore, following this path would have a clear
>>> impact in the language.
>>> 
>>> Best,
>>> 
>>> — A
>>> 
>>>> On Jan 23, 2016, at 3:46 PM, Jacob Bandes-Storch via
>>>> swift-evolution
>>>> <swift-evolution at swift.org
>>>> <mailto:swift-evolution at swift.org>>
>>>> wrote:
>>>> 
>>>> On Sat, Jan 23, 2016 at 12:44 PM, J. Cheyo Jimenez via
>>>> swift-evolution
>>>> <swift-evolution at swift.org
>>>> <mailto:swift-evolution at swift.org>>
>>>> wrote:
>>>> The inPlace proposal is excellent. As suggested something like
>>>> x.=f() would be perfect to distinguish mutating methods .Something
>>>> I don't like from the API design guidelines is that non mutating
>>>> methods like enumerate would be become enumerated. In my mind
>>>> enumerate is a word of art and I don't ever think of it as muting
>>>> so having to always use enumerated in the future seems weird. Also
>>>> having to ed/ing non mutating methods seems to make mutating
>>>> methods more important.
>>>> 
>>>> //non mutating suggestion
>>>> x.sort()
>>>> x.split()
>>>> 
>>>> //other ideas for mutating methods names
>>>> x.sort*()
>>>> x.sort&() // I like & the most
>>>> x.split&()
>>>> x.sort@()
>>>> 
>>>> By marking a method with a special character at the end, the
>>>> reader would know that the method mutates.
>>>> 
>>>> Ruby uses ! for this, by convention:
>>>> http://stackoverflow.com/questions/612189/why-are-exclamation-marks-used-in-ruby-methods
>>>> <http://stackoverflow.com/questions/612189/why-are-exclamation-marks-used-in-ruby-methods>
>>>> 
>>>> _______________________________________________
>>>> swift-evolution mailing list
>>>> swift-evolution at swift.org
>>>> <mailto:swift-evolution at swift.org>
>>>> https://lists.swift.org/mailman/listinfo/swift-evolution
>>>> <https://lists.swift.org/mailman/listinfo/swift-evolution>
>>> _______________________________________________
>>> swift-evolution mailing list
>>> swift-evolution at swift.org
>>> <mailto: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
>
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution

-- 
-Dave