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

[Ricardo Parada]

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





> 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>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160201/541cbc8b/attachment.html>