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

[Rod Brown]

My apologies. Mail failed and sent my review off early!

I can't believe I let it get this far before I began to post regarding these language proposals.

> What is your evaluation of the proposal?
I like the proposal, and the direction it shows for Swift. I'm particularly fond of the concise nature of the language.

I wonder specifically whether cases of ivars should be lower or upper case. I tend to think lower case makes more sense in the context of Swift, but I am personally fond of the upper camel case. Perhaps my eyes have just grown accustomed?

I am particularly in favour of the sort() vs sorted() verb vs noun. I definitely see the points raised and acknowledge that the subtleties of language mean there will always be exceptions to rules where it doesn't make sense, and I think the "inPlace" wording makes sense to fill this gap.

I'm personally not a fan of the strong guidance to eliminate initial argument labels. I find this somewhat of a holdover from the awkward translation of Obj-C APIs, and I think there are cases where the initial parameter makes sense to be named. The login example, while it has its flaws, makes some sense here.

loginWithUsername("Rod", password: "Password")
vs
login(username:"Rod", password: "Password")

Placing the WithUsername prior to the bracket implies that the username has more importance, at least to my eye. As has been discussed, it probably does have more importance, but I think it makes a fair point that there are cases where both arguments are simply peers that should be labeled without emphasis on the leading item. I think that naming each parameter for clarity makes sense in those cases, and this should be noted in documentation. 

For all other elements, I am definitely in favour.


> Is the problem being addressed significant enough to warrant a change to Swift?
I definitely think the language benefits from guidance like this. I wonder whether we may need to come back and review this in a few years as we see where Swift goes, but my hope is it keeps the same basic feel.


> Does this proposal fit well with the feel and direction of Swift? 
These language directions seem very consistent with Swift's direction.


> If you have used other languages or libraries with a similar feature, how do you feel that this proposal compares to those?

I find languages with clear guidelines tend to be somewhat more ordered. I'm definitely in favour of the a reference document that outlines standard practice, as it is beneficial both when teaching, and when reading people's code. Consistency breeds clarity, and these types of guides help consistency between developers.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160201/19748cf2/attachment.html>