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

Alex Migicovsky migi at apple.com
Mon Feb 1 20:18:16 CST 2016

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

More information about the swift-evolution mailing list