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

[Janosch Hildebrand]

> On 02 Feb 2016, at 01:26, 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(?)

That would also be great. Although I still think including it in the book would
be more effective. Not everyone is going to follow a link and split their attention
between two documents...
Would it be possible to include the guidelines and preface them with a note that
the most up-to date version can always be found on the web with the link there?

>> * 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. :-)

Fair enough :-)

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

I certainly agree that that should be the goal (to have basic guidelines that is,
although preserving your sanity is a close second ;-))

What is the plan in this area; will this be a future discussion/proposal to amend
the guidelines?

I was wondering whether it might make sense to have a separate thread collect
"rules" and guidelines in this area from the community to see what's out there
in the hope of eventually paring them down to some useful essentials...

> -- 
> -Dave
> 
> _______________________________________________
> 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>
- Janosch

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160202/9fe52b4c/attachment.html>