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

[Dave Abrahams]

on Mon Feb 01 2016, Ricardo Parada <swift-evolution at swift.org> wrote:

>> supportsVideoMirroring -> isVideoMirroringSupported
>> supportsVideoOrientation -> isVideoOrientationSupported
>
> IMHO, for this particular case, I think the ones on the left read more
> as assertions about the receiver than the alternatives on the right.
> I may be wrong, but I did not interpret this guideline as having to
> prefix boolean properties with is.  I think these two would be fine as
> supportVideMirroring and supportVideoOrientation as they read as
> assertions about the receiver.

+1 to all of that.

>
>> On Feb 1, 2016, at 2:51 AM, Colin Cornaby via swift-evolution
>> <swift-evolution at swift.org> wrote:
>> 
>> I’m still processing all my thoughts on this and might have a
>> thought or two on the Obj-C bridging thread as well, but I had a
>> question about one specific style guideline:
>> 
>>> Uses <> of nonmutating Boolean methods and properties should read
>>> as assertions about the receiver, e.g. x.isEmpty,
>>> line1.intersects(line2)
>> 
>> 
>> I have really mixed feelings on this, and was wondering what the
>> rationale was (maybe to convince me it’s a good idea.) To me, this
>> seems like adding extra language to a proposal that is pretty good
>> at removing now unnecessary language. It also seems unhelpful to me
>> as an API user and writer because in an alphabetical list, related
>> functionality (like a “playing” nonmutating property and a “play”
>> function, or a “playRate” mutable property) are all going to be
>> moved away from each other in a list. I acknowledge that Xcode’s
>> autocomplete is getting better though in that regard, and that most
>> documentation is grouped. But I’m not a fan of the crowding of “is”
>> functions that is going to happen.
>> 
>> In reviewing AVFoundation specifically (but I’m going through the
>> others as well), I’m not sure this is an improvement either.
>> 
>> Mildly worse, makes it sound like a function instead of a property:
>> exposurePointOfInterestSupported -> isExposurePointOfInterestSupported
>> 
>> Same sort of thing, I’m not sure this is cleaner:
>> supportsVideoMirroring -> isVideoMirroringSupported
>> 
>> This one almost sounds to me like the function meaning is being tweaked:
>> videoMirrored -> isVideoMirrored
>> 
>> The name of this one now sounds like it is supposed to have an
>> argument to check to see if a specific video orientation is
>> supported (although it is true that the original property wasn’t
>> named great either):
>> supportsVideoOrientation -> isVideoOrientationSupported
>> 
>> Like I said, I’d be willing to be talked into this, but at this
>> point I’m just really curious what the justification is. For simple
>> cases this seems to work well, but I’m really not enthused for what
>> this does to more complex or domain specific property names. I’m
>> willing to call this “unease after doing Obj-C too long”, but I’d
>> like to understand why the Swift team feels this is better.
>> 
>>> On Jan 22, 2016, at 1:02 PM, Douglas Gregor via swift-evolution
>>> <swift-evolution at swift.org
>>> <mailto:swift-evolution at swift.org>>
>>> wrote:
>>> 
>>> Hello Swift community,
>>> 
>>> The review of SE-0023"API Design Guidelines" begins now and runs
>>> through January 31, 2016. The proposal is available here:
>>> 
>>> https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md
>>> <https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.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/0023-api-guidelines.md
>>> <https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.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
>>> <https://lists.swift.org/mailman/listinfo/swift-evolution>
>> 
>> _______________________________________________
>> swift-evolution mailing list
>> swift-evolution at swift.org
>> <mailto:swift-evolution at swift.org>
>> https://lists.swift.org/mailman/listinfo/swift-evolution
>> <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