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

Tue Feb 2 12:49:20 CST 2016

on Tue Feb 02 2016, Janosch Hildebrand <swift-evolution at swift.org> wrote:

>> On 02 Feb 2016, at 02:41, Dave Abrahams via swift-evolution
>> <swift-evolution at swift.org> wrote:
>> 
>> on Mon Feb 01 2016, Janosch Hildebrand
>> <swift-evolution at swift.org
>
>> <mailto:swift-evolution at swift.org>>
>> wrote:
>> 
>>> I'm generally in favor of the proposed changes. I'll just note some
>>> minor points and disagreements:
>>> 
>>> * Like I mentioned in my SE-0023 review, I would be OK with keeping
>>> the "Type" suffix for protocols but have no strong preference.
>>> 
>>> * I'm in favor of keeping `precondition()`. `require()` might be
>>> easier to grasp at first but personally I really came to like
>>> `precondition()`.
>>> It fells both precise and I prefer the passive `precondition()` to the
>>> active `require()` for this case. To me it fits the primary meaning
>>> better; stating an API contract. The fact that the condition is
>>> actively checked is secondary to that.
>>> 
>>> * I also agree with Radosław in that I prefer `removeAll(keepCapacity:
>>> Bool)` to `removeAll(keepingCapacity: Bool)`.
>> 
>> Why?
>> 
>> I had a hard time justifying "keeping" to myself for a while, but
>> eventually I realized that this pattern is less ambiguous, at least in
>> general, since many verbs are also nouns.  Okay, "keeps" haven't been
>> considered high-tech construction elements since the middle ages, but
>> it's easy to understand how you'd be interested in the capacity of a
>> keep.
>
> :-)
> You are right, it's definitely less ambiguous in general. I'm just not sure
> how often that ambiguity actually arises in practice and if it's often enough to
> justify always using the clearer but less beautiful style, even if it often actually
> might not be necessary...

I am not convinced there's an objective aesthetic winner here.  
It's consistent with our aims to have method names that cause their
invocations to very clearly describe semantics.  To me, that is the mark
of a beautiful API.

When I didn't think it was clearer, I argued that in the absence of
other criteria, the shorter name (“keepCapacity”) should win, but
overall, the use of the past particple for these kinds of parameters
emphasizes that they modify an aspect of the behavior of the method,
which has the primary verb; they are not independent commands.  So I
think the three extra characters pay for themselves.  It has the added
benefit of satisfying those for whom being able to speak the method name
fluently is an important factor.

> At least in these cases here i find the imperative to be perfectly
> clear, especially given the surrounding context but you might have a
> better idea what the average case might look like...
>
> Also there is of course something to be said for consistency and I'm probably
> going to get used to this with time; I'm just not quite there yet ;-)
>
> It's also a bit more sentence-like: 
> * "remove all; how?, ... by keeping capacity)"
> vs
> * "remove all! keep (the) capacity!"
> but then again the new guidelines and ongoing discussion on SE-0005
> generally move away from that anyway so that doesn't seem to be a big factor.
>
> </ramble>
>
> Speaking of this change, shouldn't  `split(_, maxSplits:, omitEmptySubsequences:)`
> become `split(_, maxSplits:, omittingEmptySubsequences:)` as well or am I
> missing something?

You make a good point.

>
>>> * What is the rationale for moving `unsafeUnwrap` into Optional but
>>> not `unsafeAddressOf` into AnyObject? 
>> 
>> Language limitation: AnyObject can't be modified or extended.
>
> Thanks! (To Brent as well). That makes sense of course.
>
> Still not sure how I feel about making these functions so accessible
> but I guess that issue should be solved differently if at all.
>
>>> I can certainly see the safety argument against moving it but I don't
>>> see how that would apply to `unsafeAddressOf` but not `unsafeUnwrap`?
>>> 
>>> * `EnumeratedSequence` and `Repeated` feel weird to me. They make
>>> sense given the API guidelines and the previous `EnumerateSequence`
>>> and `Repeat` were a bit clunky as well but these somehow feel a bit
>>> worse... That might be wholly subjective though and I don't really
>>> have a good suggestion. The only thing that came to mind was
>>> `EnumerationSequence` and `Repetition` but I'm not overly fond of
>>> those either especially not to the point of deviating from the norm...
>> 
>> Yes, they're a little clunky.  No, I don't have any better ideas either
>> :-)
>
> Well, at least I'm not alone then :D
>
>>> * This is not a disagreement but I'd be interested in hearing the
>>> reasons for replacing Generator(Type) with Iterator(Protocol) if
>>> someone finds the time. I can speculate of course but it's probably
>>> easier for someone to give me a short summary :-)
>> 
>> I think these messages give all the details:
>> 
>> http://news.gmane.org/find-root.php?message_id=m2h9i4gffx.fsf%40eno.apple.com
>> <http://news.gmane.org/find-root.php?message_id=m2h9i4gffx.fsf%40eno.apple.com>
>> http://article.gmane.org/gmane.comp.lang.swift.evolution/5344
>> <http://article.gmane.org/gmane.comp.lang.swift.evolution/5344>
>
> Sorry, maybe I'm missing something or my question was unclear, but
> isn't that more the rationale for dropping the "Type" suffix?
>
> I'm asking more about the switch from `Generator` to `Iterator` and
> by that argument wouldn't `GeneratorProtocol` work just as well?
>
> My assumption was that the switch was probably motivated by
> a) Iterator is the more well known concept
> b) Generator is more of a term of art and IIUC Swift's Generators
> aren't Generators in the strictest sense
>
> but I could be wrong in a lot of ways, hence why I'm asking :-)
>
>>> * Typo: 
>>>> +  public func take() -> Memory // Should be Pointee
>> 
>> Nice, thanks.
>> 
>> -- 
>> -Dave
>> 
>> _______________________________________________
>> 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>
> - Janosch
>
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution

-- 
-Dave