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

Janosch_Hildebrand · February 2, 2016, 6:16pm

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

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@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution

- Janosch

···

On 02 Feb 2016, at 02:41, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:
on Mon Feb 01 2016, Janosch Hildebrand <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:

dabrahams · February 5, 2016, 9:35pm

And what do you think it *should* say?

···

on Fri Feb 05 2016, Ben Rimmington <swift-evolution@swift.org> wrote:

Proposal link:

<https://github.com/apple/swift-evolution/blob/master/proposals/0006-apply-api-guidelines-to-the-standard-library.md>

precondition was renamed to require.

In the Standard Library, "- Requires:" appears in documentation
comments more often than "- Precondition:" or "- Postcondition:", so
renaming the function makes sense.

However, I think the Xcode Markup Formatting Reference should be
updated to reflect this usage. The current description is:

Use the field to add requirements such as frameworks for using the symbol.

/**
An example of using the requires field

- requires: Contacts framework
- requires: OS X version 10.11 or better
*/

<https://developer.apple.com/library/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Requires.html>

--
-Dave

benrimmington · February 5, 2016, 10:29pm

You seem to be using the "- Requires:" field as an alternative to the "- Precondition:" field. Here are some examples from the Standard Library (Swift 2.1):

/// - Requires: `start <= end`.
/// - Requires: `count > 0`.
/// - Requires: `i <= count`.
/// - Requires: `s` contains exactly one extended grapheme cluster.
/// - Requires: No preceding call to `self.next()` has returned `nil`.
/// - Requires: The next value is representable.

If this usage is correct, I'm suggesting that the Xcode Markup Formatting Reference pages for "- Requires:" and "- Precondition:" should be basically the same.

To document framework/platform dependencies (that the "- Requires:" field was apparently designed for) you could instead add a new "- Dependency:" field.

-- Ben

···

On 5 Feb 2016, at 21:35, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

on Fri Feb 05 2016, Ben Rimmington <swift-evolution@swift.org> wrote:

Proposal link:

<https://github.com/apple/swift-evolution/blob/master/proposals/0006-apply-api-guidelines-to-the-standard-library.md>

precondition was renamed to require.

In the Standard Library, "- Requires:" appears in documentation
comments more often than "- Precondition:" or "- Postcondition:", so
renaming the function makes sense.

However, I think the Xcode Markup Formatting Reference should be
updated to reflect this usage. The current description is:

Use the field to add requirements such as frameworks for using the symbol.

/**
An example of using the requires field

- requires: Contacts framework
- requires: OS X version 10.11 or better
*/

<https://developer.apple.com/library/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Requires.html>

And what do you think it *should* say?

griotspeak · January 23, 2016, 7:38pm

I agree that the need to immediately wrap in a BufferPointer is awkward.
I've been consistently thrown by the fact that we specify how many items to
allocate on the 'single' pointers, though.

···

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

> On Jan 22, 2016, at 11:31 PM, Guillaume Lessard via swift-evolution < > swift-evolution@swift.org> wrote:
>
> Hello,
>
> I disagree with the following change to UnsafeMutablePointer:
> - public static func alloc(num: Int) -> UnsafeMutablePointer<Pointee>
> + public init(allocatingCapacity count: Int)
>
> This would make it the only constructor in any of OpaquePointer,
UnsafePointer, UnsafeMutablePointer and UnsafeReference to have the
side-effect of allocating memory. All the others are relatively cheap
transformations on pointer values, and get used a lot for typecasting. An
allocating constructor would be less locatable among such uses of
typecasting-via-constructor. The memory-allocating static method has the
merit of sticking out, and pairs nicely with the necessary deallocation
call, like the malloc/free pair.

This all probably deserves a separate discussion from the overall umbrella
proposal. Another thing to consider here is whether the logic to allocate
an array of values really belongs on UnsafeMutablePointer—it seems like a
better fit for UnsafeMutableBufferPointer, whose whole job is to reference
an array of objects in memory. Currently, you need to allocate the memory
using UnsafeMutablePointer.alloc, then immediately wrap it in a
BufferPointer with the same count, which is a bit awkward.

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

dabrahams · January 24, 2016, 10:27pm

Hello,

I disagree with the following change to UnsafeMutablePointer:

- public static func alloc(num: Int) -> UnsafeMutablePointer<Pointee>
+ public init(allocatingCapacity count: Int)

This would make it the only constructor in any of OpaquePointer,
UnsafePointer, UnsafeMutablePointer and UnsafeReference to have the
side-effect of allocating memory. All the others are relatively
cheap transformations on pointer values, and get used a lot for
typecasting. An allocating constructor would be less locatable among
such uses of typecasting-via-constructor. The memory-allocating
static method has the merit of sticking out, and pairs nicely with
the necessary deallocation call, like the malloc/free pair.

This all probably deserves a separate discussion from the overall
umbrella proposal. Another thing to consider here is whether the logic
to allocate an array of values really belongs on
UnsafeMutablePointer—it seems like a better fit for
UnsafeMutableBufferPointer, whose whole job is to reference an array
of objects in memory.

Currently, you need to allocate the memory using
UnsafeMutablePointer.alloc, then immediately wrap it in a
BufferPointer with the same count, which is a bit awkward.

You make a good point, Joe. Why would we throw out the size
information immediately after allocating the memory?

*On the other hand*, UnsafeMutableBufferPointer is really not designed
to support allocated-but-initialized memory, and I think I'd prefer to
keep it that way. I don't think once you step into unsafe-land, you
should have to live more dangerously than the individual situation
requires, and modifying part of an array without ARC overhead is an
important use-case.

For buffers with some uninitialized elements we have ManagedBuffer et
al., but of course that doesn't cover the use-case of manual memory
deallocation. So maybe a different component altogether—or some kind of
more-general unification of these components—is what we need in the long
run. Definitely more appropriate to pursue this in another thread.

···

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

On Jan 22, 2016, at 11:31 PM, Guillaume Lessard via swift-evolution <swift-evolution@swift.org> wrote:

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

--
-Dave

dabrahams · January 27, 2016, 12:39am

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.

···

on Tue Jan 26 2016, Charles Kissinger <swift-evolution@swift.org> wrote:

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@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:
[swift-evolution] [Review] SE-0005 Better Translation of Objective-C APIs Into Swift
<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@swift.org >>> <mailto:swift-evolution@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
<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>
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

_______________________________________________
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

dabrahams · January 27, 2016, 8:49am

But that's not how they're used. I'd have to rename Equatable and
Comparable to follow that convention.

···

on Tue Jan 26 2016, Dave <swift-evolution@swift.org> wrote:

On Jan 25, 2016, at 07:40, Radosław Pietruszewski via >> swift-evolution <swift-evolution@swift.org> wrote:

== 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”.

Same here… I like -Type for protocols that can only be used a generic
constraint, and -able/-ible for protocols that can be “concrete”
types.

--
-Dave

Brent_Royal-Gordon · January 30, 2016, 2:43am

Count me among those who liked the ‘Type’ suffix for protocols though.

I wonder if we can't change it to a -`like` suffix. Applying that to 2.1 stdlib gives you:

AnyCollectionlike
BidirectionalIndexlike
BitwiseOperationslike
Booleanlike
CVarArglike
Collectionlike
Errorlike
FloatingPointlike
ForwardIndexlike
Generatorlike
IntegerArithmeticlike
Integerlike
Intervallike
LazyCollectionlike
LazySequencelike
MirrorPathlike
MutableCollectionlike
OptionSetlike
OutputStreamlike
RandomAccessIndexlike
RangeReplaceableCollectionlike
ReverseIndexlike
Sequencelike
SetAlgebralike
SignedIntegerlike
SignedNumberlike
UnicodeCodeclike
UnsignedIntegerlike

Not all of these are perfect, but in some cases that's because they should arguably be -able protocols (BitwiseOperationsType -> BitwiseOperable).

···

--
Brent Royal-Gordon
Architechies

dabrahams · February 2, 2016, 4:57pm

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.

Why not, though? adding `-ing`s in this context has all of the
problems -ed/-ing has with method names,

Which problems, sorry?

and none of the necessity of conveying mutability information.

What’s wrong with “keepCapacity” as a parameter name?

It can be interpreted as denoting the capacity of the keep.

···

on Tue Feb 02 2016, Radosław Pietruszewski <swift-evolution@swift.org> wrote:

On 02 Feb 2016, at 02:41, Dave Abrahams via swift-evolution >> <swift-evolution@swift.org> wrote:
on Mon Feb 01 2016, Janosch Hildebrand <swift-evolution@swift.org> wrote:

* What is the rationale for moving `unsafeUnwrap` into Optional but
not `unsafeAddressOf` into AnyObject?

Language limitation: AnyObject can't be modified or extended.

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
:-)

* 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://article.gmane.org/gmane.comp.lang.swift.evolution/5344

* Typo:

+ public func take() -> Memory // Should be Pointee

Nice, thanks.

--
-Dave

_______________________________________________
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

dabrahams · February 2, 2016, 6:49pm

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.

···

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

On 02 Feb 2016, at 02:41, Dave Abrahams via swift-evolution >> <swift-evolution@swift.org> wrote:
on Mon Feb 01 2016, Janosch Hildebrand >> <swift-evolution@swift.org > >> <mailto:swift-evolution@swift.org>> >> wrote:

* 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@swift.org
<mailto:swift-evolution@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@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

--
-Dave

dabrahams · February 2, 2016, 6:52pm

* 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

+1

b) Generator is more of a term of art and IIUC Swift's Generators
aren't Generators in the strictest sense

Not that one so much, IIRC. The main thing was that to at least one
person, the method name “generate()” was obviously wrong and hard to
tolerate. Once you start thinking about other names for that, it leads
naturally to considering other names for the things it returns.

···

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

but I could be wrong in a lot of ways, hence why I'm asking :-)

--
-Dave

Janosch_Hildebrand · February 2, 2016, 7:42pm

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.

You make a strong case but I think this is just one of those cases where I'm
reluctant to commit to anything before getting a feel for the code which simply
takes time :-) So I think I'll just defer to your better judgment for now.

This (meaning the guidelines, not just this point) is probably an area that might
get some more feedback anyway once people have actually used them for a while
so I'll come back to this then if it still irks me.

Anyway, thanks a lot for taking the time!

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://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@swift.org <mailto:swift-evolution@swift.org>
<mailto:swift-evolution@swift.org <mailto:swift-evolution@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@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution

--
-Dave

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

- Janosch

···

On 02 Feb 2016, at 19:49, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:
on Tue Feb 02 2016, Janosch Hildebrand <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:

On 02 Feb 2016, at 02:41, Dave Abrahams via swift-evolution >>> <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:
on Mon Feb 01 2016, Janosch Hildebrand >>> <swift-evolution@swift.org <mailto:swift-evolution@swift.org> >> >>> <mailto:swift-evolution@swift.org <mailto:swift-evolution@swift.org>>> >>> wrote:

Radek_Pietruszewski · February 2, 2016, 10:09pm

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.

Why not, though? adding `-ing`s in this context has all of the
problems -ed/-ing has with method names,

Which problems, sorry?

A bit of extra spelling gymnastics… Maybe I’m the only one bothered by this, but I’d just prefer a shorter/simpler name in absence of a compelling reason to do otherwise. (You did make an argument for why in a later post, fwiw. I’m not super compelled by it, but also don’t feel so strongly against the `ing` to argue further ;) )

and none of the necessity of conveying mutability information.

What’s wrong with “keepCapacity” as a parameter name?

It can be interpreted as denoting the capacity of the keep.

Wow, that… would have never crossed my mind ;)

···

* What is the rationale for moving `unsafeUnwrap` into Optional but
not `unsafeAddressOf` into AnyObject?

Language limitation: AnyObject can't be modified or extended.

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
:-)

* 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://article.gmane.org/gmane.comp.lang.swift.evolution/5344

* Typo:

+ public func take() -> Memory // Should be Pointee

Nice, thanks.

--
-Dave

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

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

--
-Dave

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

James_Campbell · February 9, 2016, 7:23am

I feel keepingCapacity should be a question, shouldKeepCapacity or whilstKeepingCapacity.

···

Sent from Outlook Mobile

On Tue, Feb 2, 2016 at 10:16 AM -0800, "Janosch Hildebrand via swift-evolution" <swift-evolution@swift.org> wrote:

On 02 Feb 2016, at 02:41, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:
on Mon Feb 01 2016, Janosch Hildebrand <swift-evolution@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 surehow often that ambiguity actually arises in practice and if it's often enough tojustify always using the clearer but less beautiful style, even if it often actuallymight not be necessary...At least in these cases here i find the imperative to be perfectly clear, especiallygiven the surrounding context but you might have a better idea what the averagecase might look like...
Also there is of course something to be said for consistency and I'm probablygoing 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-0005generally 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 Imissing 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 accessiblebut 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://article.gmane.org/gmane.comp.lang.swift.evolution/5344

Sorry, maybe I'm missing something or my question was unclear, butisn't that more the rationale for dropping the "Type" suffix?
I'm asking more about the switch from `Generator` to `Iterator` andby that argument wouldn't `GeneratorProtocol` work just as well?
My assumption was that the switch was probably motivated bya) Iterator is the more well known conceptb) 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@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

- Janosch

Joe_Groff · January 23, 2016, 7:56pm

I agree that the need to immediately wrap in a BufferPointer is awkward. I've been consistently thrown by the fact that we specify how many items to allocate on the 'single' pointers, though.

Definitely. It would make sense to me if UnsafeMutablePointer's allocation and deallocation APIs worked only for single values, and UnsafeMutableBufferPointer provided similar APIs to allocate and deallocate arrays.

Another thing that might be handy on both types is a `withAllocation { }` function for scoped allocations, which would dealloc for you at block exit (and maybe optionally destroy first).

-Joe

···

On Jan 23, 2016, at 11:38 AM, T.J. Usiyan <griotspeak@gmail.com> wrote:

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

> On Jan 22, 2016, at 11:31 PM, Guillaume Lessard via swift-evolution <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:
>
> Hello,
>
> I disagree with the following change to UnsafeMutablePointer:
> - public static func alloc(num: Int) -> UnsafeMutablePointer<Pointee>
> + public init(allocatingCapacity count: Int)
>
> This would make it the only constructor in any of OpaquePointer, UnsafePointer, UnsafeMutablePointer and UnsafeReference to have the side-effect of allocating memory. All the others are relatively cheap transformations on pointer values, and get used a lot for typecasting. An allocating constructor would be less locatable among such uses of typecasting-via-constructor. The memory-allocating static method has the merit of sticking out, and pairs nicely with the necessary deallocation call, like the malloc/free pair.

This all probably deserves a separate discussion from the overall umbrella proposal. Another thing to consider here is whether the logic to allocate an array of values really belongs on UnsafeMutablePointer—it seems like a better fit for UnsafeMutableBufferPointer, whose whole job is to reference an array of objects in memory. Currently, you need to allocate the memory using UnsafeMutablePointer.alloc, then immediately wrap it in a BufferPointer with the same count, which is a bit awkward.

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

Chris_Lattner · January 23, 2016, 8:50pm

I agree, that makes a lot of sense.

-Chris

···

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

On Jan 23, 2016, at 11:38 AM, T.J. Usiyan <griotspeak@gmail.com <mailto:griotspeak@gmail.com>> wrote:

I agree that the need to immediately wrap in a BufferPointer is awkward. I've been consistently thrown by the fact that we specify how many items to allocate on the 'single' pointers, though.

Definitely. It would make sense to me if UnsafeMutablePointer's allocation and deallocation APIs worked only for single values, and UnsafeMutableBufferPointer provided similar APIs to allocate and deallocate arrays.

Dany_St-Amant1 · January 27, 2016, 2:06am

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.

Dany

···

Le 26 janv. 2016 à 19:39, Dave Abrahams via swift-evolution <swift-evolution@swift.org> a écrit :
on Tue Jan 26 2016, Charles Kissinger <swift-evolution@swift.org> wrote:

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@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:
[swift-evolution] [Review] SE-0005 Better Translation of Objective-C APIs Into Swift
<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@swift.org >>>> <mailto:swift-evolution@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
<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>
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

_______________________________________________
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

David_Sweeris · January 27, 2016, 9:23am

Huh… Yeah, you’re right. I guess I saw “CollectionType” and “CustomStringConvertible” or something and made a connection that wasn’t there.
Well, FWIW, that convention (plus the occasional “HasNoun”, and -ableType for constraining the element of custom collections) tends to work well for me.

What’s been the deciding factor between -Type and -able so far?

- Dave Sweeris

···

On Jan 27, 2016, at 00:49, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

on Tue Jan 26 2016, Dave <swift-evolution@swift.org> wrote:

On Jan 25, 2016, at 07:40, Radosław Pietruszewski via >>> swift-evolution <swift-evolution@swift.org> wrote:

== 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”.

Same here… I like -Type for protocols that can only be used a generic
constraint, and -able/-ible for protocols that can be “concrete”
types.

But that's not how they're used. I'd have to rename Equatable and
Comparable to follow that convention.

--
-Dave

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

trs · January 29, 2016, 3:29pm

I'm fine with "require", especially as I've been introduced to pre- and postconditions by Bertrand Meyer's Eiffel, which uses "require" for preconditions and "ensure" for postconditions and is still the only language that I know that has these baked into the language including proper behavior in the face of inheritance.

-Thorsten

···

Am 27.01.2016 um 01:39 schrieb Dave Abrahams via swift-evolution <swift-evolution@swift.org>:

on Tue Jan 26 2016, Charles Kissinger <swift-evolution@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.

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@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:
[swift-evolution] [Review] SE-0005 Better Translation of Objective-C APIs Into Swift
<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@swift.org >>>> <mailto:swift-evolution@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
<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>
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

_______________________________________________
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

migi · January 30, 2016, 2:47am

IMO the ‘like’ suffix makes it sound like the conforming type to Collectionlike is like a Collection, but not exactly a Collection. Maybe there’s another suffix that works but I don’t think this one conveys the right information.

- Alex

···

On Jan 29, 2016, at 6:43 PM, Brent Royal-Gordon via swift-evolution <swift-evolution@swift.org> wrote:

Count me among those who liked the ‘Type’ suffix for protocols though.

I wonder if we can't change it to a -`like` suffix. Applying that to 2.1 stdlib gives you:

AnyCollectionlike
BidirectionalIndexlike
BitwiseOperationslike
Booleanlike
CVarArglike
Collectionlike
Errorlike
FloatingPointlike
ForwardIndexlike
Generatorlike
IntegerArithmeticlike
Integerlike
Intervallike
LazyCollectionlike
LazySequencelike
MirrorPathlike
MutableCollectionlike
OptionSetlike
OutputStreamlike
RandomAccessIndexlike
RangeReplaceableCollectionlike
ReverseIndexlike
Sequencelike
SetAlgebralike
SignedIntegerlike
SignedNumberlike
UnicodeCodeclike
UnsignedIntegerlike

Not all of these are perfect, but in some cases that's because they should arguably be -able protocols (BitwiseOperationsType -> BitwiseOperable).

--
Brent Royal-Gordon
Architechies

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