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

[Dave Abrahams]

on Mon Feb 01 2016, Alex Migicovsky <migi-AT-apple.com> wrote:

>> On Feb 1, 2016, at 4:26 PM, Dave Abrahams via swift-evolution
>> <swift-evolution at swift.org> wrote:
>> 
>> 
>> on Mon Feb 01 2016, Janosch Hildebrand <swift-evolution at swift.org
>
>> <mailto:swift-evolution at swift.org>> wrote:
>> 
>>> I'd like to add my voice to the many that are in favor of this proposal.
>>> 
>>> I agree with the general spirit of the guidelines and I think they
>>> cover the most important points. They can always be expanded in the
>>> future if experience deems it necessary but I'd rather have people
>>> actually read and use the document than be put off by length and
>>> complexity.
>>> 
>>> Various minor points
>>> 
>>> * Will these guidelines become part of "The Swift Programming
>>> Language"? Personally I would support that.
>> 
>> Interesting idea.  I think we may need the ability to update them on a
>> different schedule form the book.  Perhaps the book should point at
>> them, though(?)
>> 
>>> * I'm in favor of lowerCaseEnumCases
>>> 
>>> * var htmlElement = HTMLElement
>>> 
>>> * I don't think stripping the "Type" suffix from protocols is a clear
>>> win, mostly a change of tradeoffs (which have already been discussed
>>> extensively).
>>> Ultimately I would be fine with either approach.
>>> 
>>> * One small idea I'd like to throw out there is whether the guidelines
>>> should contain a small note that one might look to the standard
>>> library for inspiration as well. It will have many examples for
>>> following the guidelines as presented and might offer some helpful
>>> precedent in cases where one is still unsure. In a way this is
>>> probably obvious but it might not hurt to mention?
>> 
>> Well, maybe.  If you mention all the things that wouldn't hurt to
>> mention... it ends up hurting :-) Trying to “omit needless words,”
>> here. :-)
>> 
>>> * On the guidelines page the bullet point "When the first argument is
>>> defaulted, it should have a distinct argument label." is wrapped in a
>>> link (without a target). This is probably unintentional.
>> 
>> Actually, there's no link!  This looks like a .css error, thanks.  I've
>> alerted the CSS-master.
>> 
>>> And a bit of rambling regarding the property vs method discussion:
>>> The current situation seems to be that there are a lot of conflicting
>>> "rules" (most with exceptions attached) that need to be weighed
>>> against each other, with the decision coming down to "collective gut
>>> feeling". 
>> 
>> Unfortunately, I agree with that assessment.
>> 
>>> It don't see a way to formalize them without breaking at least some
>>> existing conventions and probably some heated discussions ;-). I also
>>> wonder if that would actually produce better APIs on the whole or
>>> simply produce clear rules for the sake of having clear rules with
>>> APIs suffering in some cases...
>> 
>> Aside from the issues I've mentioned before of non-uniformity and wasted
>> cycles bikeshedding trivial choices, there's another problem with not
>> saying anything in this *particular* case...
>> 
>> Despite the Cocoa guidelines never explicitly stating that anything
>> *must* be a property, there is apparently an unwritten but very strong
>> rule among Cocoa developers that "unless the guidelines say it can't be
>> a property, it must be a property."  People coming from that perspective
>> have looked at individual methods (in the standard library for example)
>> and insisted with great conviction that they ought to be properties.
>> However, if you ask them to look at the whole body of APIs, they come to
>> different conclusions (e.g. that APIs producing transformed
>> representations of collections, such as "x.reverse()," ought to be
>> methods, not properties).  If nothing else, to preserve *my* sanity, I
>> need a guideline I can refer to.  ;-) Even if it has some fuzzy edges,
>> that's better than nothing.
>
> Just wanted to clarify the rule a bit. The strong rule in Cocoa APIs
> is that if a zero-arg method is idempotent it should be a property. 

...unless it falls into one of the other categories (such as “copy” and
autorelease methods, methods which initiate an action and return a
result, etc.) that makes it ineligible to be a property.

> In my opinion this has proven to be a rule that provides enough value
> at call sites, but is also a straightforward guideline to follow. I
> can see the perspective of APIs like `reversed` being a method and not
> a property, but then it really does muddy the waters for coming up
> with a simple to follow but useful rule. Tradeoffs… :-)
>
> - Alex

-- 
-Dave