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

[Janosch Hildebrand]

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.

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

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


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

- Janosch

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