[swift-evolution] [Review] SE-0006 Apply API Guidelines to the Standard Library

Charles Kissinger crk at akkyra.com
Wed Jan 27 15:56:22 CST 2016 

> On Jan 26, 2016, at 11:07 PM, Dave Abrahams via swift-evolution <swift-evolution at swift.org> wrote:
> 
> 
> on Tue Jan 26 2016, Dany St-Amant <swift-evolution at swift.org> wrote:
> 
>>> Le 26 janv. 2016 à 19:39, Dave Abrahams via swift-evolution
>>> <swift-evolution at swift.org> a écrit :
>>> 
>>> 
>>> on Tue Jan 26 2016, Charles Kissinger <swift-evolution at swift.org> wrote:
>>> 
>>>> I agree with all of the small criticisms mentioned below by Radoslaw
>>>> except for the renaming of precondition() to require(). I think it is
>>>> an improvement that it describes an action now, just like assert().
>>> 
>>> Interestingly, I was the one that insisted on that change, as I felt
>>> “precondition” was too much of a term-of-art and “require” would be more
>>> accessible, but I am now regretting that decision.  This function is not
>>> conceptually an action; like “assert,” it's a declarative statement, and
>>> “precondition” conveyed that aspect much better, IMO.
>> 
>> How about expect()? Should not have much string attached to it. Only
>> thing coming to mind is the
>> TCL extension used for automation.
> 
> That is, again, more action-y and less declarative.  We could go with
> "expected," of course, but in either case we're just inventing names for
> something that already has a perfectly good name.  Precondition is a
> term of art with a precise meaning.  Does anybody on this list feel that
> "precondition" is too inaccessible?

‘Precondition’ is not particularly bad jargon since it is a standard dictionary word that is used with a similar meaning in areas outside of computer science. ‘Require’ probably has an advantage with students and non-native English speakers by virtue of being a much more commonly used and understood word.

—CK

> 
>> 
>> 
>> Dany
>> 
>>> 
>>>> 
>>>> Count me among those who liked the ‘Type’ suffix for protocols though.
>>>> 
>>>> —CK
>>>> 
>>>>> On Jan 25, 2016, at 7:40 AM, Radosław Pietruszewski via
>>>>> swift-evolution
>>>>> <swift-evolution at swift.org> wrote:
>>>>> 
>>>>> Hello all,
>>>>> 
>>>>> Just like with SE-0005
>>>>> <https://lists.swift.org/pipermail/swift-evolution/Week-of-Mon-20160125/007658.html>,
>>>>> I’m overwhelmingly for this proposal. The Guidelines, as a whole do
>>>>> a great job at making Swift APIs more consistent and clearer, and
>>>>> applying them to the Swift stdlib is an important first step.
>>>>> 
>>>>> * * *
>>>>> 
>>>>> Nitpicks, criticisms and suggestions:
>>>>> 
>>>>> == precondition was renamed to require ==
>>>>> 
>>>>> This might be confusing to newcomers, as many languages use the word
>>>>> `require` as a keyword for what we'd call `import`. Although a bit
>>>>> more technical, `precondition` is unambiguous and still easily
>>>>> understandable. I feel like `required` does more damage than good.
>>>>> 
>>>>> == Removed Type from protocol names ==
>>>>> 
>>>>> Perhaps I’ve missed some discussion about this and I don’t see the
>>>>> context, but I’m not sure this is a positive change.
>>>>> 
>>>>> I fear this might be confusing in practice, at least in some
>>>>> contexts. For example, there's nothing signifying that "Boolean" or
>>>>> "Integer" are protocols and not actual types. Same with “Sequence”,
>>>>> “OptionSet”, etc. Perhaps it doesn't matter because everyone will
>>>>> naturally go for `Bool`, `Int`, and `Array` anyway. But I can
>>>>> imagine a lot of confusion if someone tried that anyway, or perhaps
>>>>> saw that in the autocompletion, or the standard library browser
>>>>> (with no intention of using the protocol).
>>>>> 
>>>>> I’m all for removing unnecessary noise and verbosity, but I think I
>>>>> would err on explicitness side here. It seemed like the -able/-Type
>>>>> convention did a good job disambiguating types you can actually
>>>>> instantiate from protocols, with very little “verbosity cost”.
>>>>> 
>>>>> == sort() => sorted(), sortInPlace() => sort() etc ==
>>>>> 
>>>>> I’m torn on this.
>>>>> 
>>>>> Frankly, I find both the “foo/fooInPlace” and “bar/barred”
>>>>> conventions awkward. Both seem weird. “InPlace” isn’t something I
>>>>> recall seeing anywhere else in API naming, and seems a bizarre way
>>>>> of signifying mutability. “-ed” doesn’t work with all words, so you
>>>>> sometimes have to go with “-ing”, or give up and cry. And then you
>>>>> have inconsistency that “-InPlace” doesn’t seem to have. Also,
>>>>> -ed/-ing can sometimes be difficult to write, especially for
>>>>> non-natives because of the “last letter is doubled” rule for some
>>>>> words.
>>>>> 
>>>>> But my biggest problem with this change is that IMHO we should
>>>>> encourage to use the transforming (non-mutating) variants by
>>>>> default. One way to achieve this as an API designer and slightly
>>>>> push people towards doing what’s considered best practice is to make
>>>>> the preferable variant easier to type. This might be a subtle
>>>>> change, but I think it matters. Before, if you really wanted to
>>>>> mutate something in place, you had to do that extra little bit of
>>>>> work typing “sortInPlace”, whereas what would be preferable most of
>>>>> the time had a simpler, shorter form: “sort” and would appear
>>>>> earlier in autocomplete.
>>>>> 
>>>>> == -ings in argument names ==
>>>>> 
>>>>> I’ve noticed these few tweaks in naming:
>>>>> 
>>>>>> -  mutating func removeAll(keepCapacity keepCapacity: Bool = false)
>>>>>> +  mutating func removeAll(keepingCapacity keepingCapacity: Bool = false)
>>>>>> 
>>>>>> public func transcode<...>(...
>>>>>> -  stopOnError: Bool
>>>>>> +  stoppingOnError: Bool
>>>>>> ) -> Bool
>>>>>> 
>>>>>> +  public init(allocatingCapacity count: Int)
>>>>> 
>>>>> I'm against this change. While I'm not fully convinced of the
>>>>> -ed/-ing rule for methods and properties, it does an important job
>>>>> by conveying the non-mutating semantics of a symbol described. In
>>>>> case of argument names, this rationale no longer applies.
>>>>> 
>>>>> The only reason to write "stoppingOnError" instead of "stopOnError"
>>>>> is to make method invocations sound more like real English
>>>>> sentences. This is the conventional Objective-C thinking the
>>>>> Guidelines largely step back from. In my opinion, this is futile and
>>>>> provides no readability benefits in this context. Method invocations
>>>>> are _not_ sentences. It's not English, it's code. And while making
>>>>> method names blatantly gramatically incorrect doesn't help
>>>>> readability, neither does forcing `-ing` endings to all boolean
>>>>> function arguments.
>>>>> 
>>>>> The only thing it does is it adds a few extra characters, an extra
>>>>> word ending the reader has to parse and understand. I know that it's
>>>>> a non-goal to make Swift code as terse as possible, and I'm not
>>>>> arguing for that. But the Guidelines seem to agree that adding extra
>>>>> verbosity _without a good reason_ is a bad thing. Because every
>>>>> extra word and symbol in code just adds to the cognitive load of the
>>>>> reader. And when it doesn't serve a purpose, it just decreases the
>>>>> signal-to-noise ratio.
>>>>> 
>>>>> Plus, as mentioned before, `-ed/-ing` can be tricky to spell for
>>>>> non-natives. This might not be a big deal, but given that this
>>>>> change provides no benefits, it's one more tiny thing you have to be
>>>>> careful not to get wrong when writing Swift.
>>>>> 
>>>>> And it's unnecessary:
>>>>> 
>>>>>  removeAll(keepCapacity: true)
>>>>>  transcode(foo, bar, stopOnError: true)
>>>>> 
>>>>> Are just as clear and readable as:
>>>>> 
>>>>>  removeAll(keepingCapacity: true)
>>>>>  transcode(foo, bar, stoppingOnError: true)
>>>>> 
>>>>> And the former isn't gramatically incorrect, because this isn't a sentence.
>>>>> 
>>>>> Apologies for nitpicking on this tiniest possible detail. I just
>>>>> care a lot that we don't create a precedent of trying to make
>>>>> everything sound like English unnecessarily and add verbosity bit by
>>>>> bit.
>>>>> 
>>>>> * * *
>>>>> 
>>>>>> 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?
>>>>> Yes, and yes, with small details still worth reconsidering.
>>>>> 
>>>>>> How much effort did you put into your review? A glance, a quick
>>>>>> reading, or an in-depth study?
>>>>> 
>>>>> I’ve read the whole proposal, as well as the related proposals, and
>>>>> read the thread for this review.
>>>>> 
>>>>> Cross-linking to my SE-0005 review:
>>>>> https://lists.swift.org/pipermail/swift-evolution/Week-of-Mon-20160125/007658.html
>>>>> <https://lists.swift.org/pipermail/swift-evolution/Week-of-Mon-20160125/007658.html>
>>>>> 
>>>>> Thanks,
>>>>> — Radek
>>>>> 
>>>>>> On 22 Jan 2016, at 22:02, Douglas Gregor via swift-evolution
>>>>>> <swift-evolution at swift.org
>>>>>> <mailto:swift-evolution at swift.org>>
>>>>>> wrote:
>>>>>> 
>>>>>> Hello Swift community,
>>>>>> 
>>>>>> The review of SE-0006 "Apply API Guidelines to the Standard
>>>>>> Library" begins now and runs through January 31, 2016. The proposal
>>>>>> is available here:
>>>>>> 
>>>>>> https://github.com/apple/swift-evolution/blob/master/proposals/0006-apply-api-guidelines-to-the-standard-library.md
>>>>>> <https://github.com/apple/swift-evolution/blob/master/proposals/0006-apply-api-guidelines-to-the-standard-library.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
>>>>>> <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/0006-apply-api-guidelines-to-the-standard-library.md
>>>>>> <https://github.com/apple/swift-evolution/blob/master/proposals/0006-apply-api-guidelines-to-the-standard-library.md>
>>>>>> Reply text
>>>>>> 
>>>>>> Other replies
>>>>>> <https://github.com/apple/swift-evolution#what-goes-into-a-review-1>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
>>>>>> <https://github.com/apple/swift-evolution/blob/master/process.md>
>>>>>> Thank you,
>>>>>> 
>>>>>> -Doug Gregor
>>>>>> 
>>>>>> Review Manager
>>>>>> 
>>>>>> _______________________________________________
>>>>>> 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
>>> 
>>> _______________________________________________
>>> 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
> 
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution

More information about the swift-evolution mailing list