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

[Dave Abrahams]

on Mon Feb 01 2016, Janosch Hildebrand <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.

-- 
-Dave