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

Tue Feb 2 12:16:35 CST 2016

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

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

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