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

[Alex Migicovsky]

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