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

[Dave Abrahams]

on Sun Jan 31 2016, Colin Cornaby <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. 

http://oldtownscrabble.com/10/08/verb-and-adjective/

The classic example is:

    x.empty()

does this clear the elements of x, or just tell you whether it has any?

Lisp users have a "-p" (for "predicate") suffix they append to things to
solve this kind of problem.

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

If that's going to be an issue, we should fix the tools.

> 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

Heh, I'd go with 

    supportsExposurePointOfInterest

myself.

> Same sort of thing, I’m not sure this is cleaner:
> supportsVideoMirroring -> isVideoMirroringSupported

x.supportsVideoMirroring is how it should read.  Did we make that change
automatically?  Oh, I see, this came from
https://github.com/apple/swift-3-api-guidelines-review/commit/a6ce38eec58e8c2da901d0049a04e4b875c403b2.

This is one of the rare cases where the original property name works
better than the getter.  Looking at the rest of this change, it's IMO so
overwhelmingly positive that we'd want to just let the framework author
tweak this one explicitly with an NS_SWIFT_NAME annotation.

> This one almost sounds to me like the function meaning is being tweaked:
> videoMirrored -> isVideoMirrored

Well, I'd agree that videoIsMirrored or mirroring would be better names
in this case, but I don't think the transformation does any damage.

> 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

Another case of
https://github.com/apple/swift-3-api-guidelines-review/commit/a6ce38eec58e8c2da901d0049a04e4b875c403b2

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

The rationale is that it clarifies things that would otherwise be unclear.

HTH,

-- 
-Dave