[swift-evolution] API Guideline bugs and enhancements
Rudolf Adamkovič
salutis at me.com
Tue Jan 5 16:16:59 CST 2016
Great discussion, thanks Erika for bringing this up.
Chiming in with a little question here. The API guidelines say:
> Boolean methods and properties should read as assertions about the receiver
I know the document is about APIs but is this also recommended for local variables and constants?
Any thoughts?
Thanks!
R+
> On 5 Jan 2016, at 22:57, Daniel Steinberg via swift-evolution <swift-evolution at swift.org> wrote:
>
> I agree - there are a few I'd love to see discussed.
>
> I also agree that I appreciate that they are there and so well thought out and presented
>
> On Jan 5, 2016, at 4:26 PM, Paul Cantrell via swift-evolution <swift-evolution at swift.org <mailto:swift-evolution at swift.org>> wrote:
>
>> I’ll second Erica on wanting a place to discuss the API guidelines. In general, I like their general approach and philosophy — very much so! — but I also have concerns about some of the details. For example, I totally agree with Erica’s suggestion that all methods with side effects should be verbs, not just ones that mutate the receiver.
>>
>> You can read here a detailed writeup on the sticking points I hit trying to put the guidelines into practice on a real-world project:
>>
>> https://gist.github.com/pcantrell/22a6564ca7d22789315b <https://gist.github.com/pcantrell/22a6564ca7d22789315b>
>>
>> The acceptance rate for Apple-guideline-recommended changes come out at only about 50%.
>>
>> I realize that guidelines are just guidelines, but that seems like a bit of an easy out if the guidelines doc is meant to help unify the style of disparate Swift libraries.
>>
>> Cheers,
>>
>> Paul
>>
>>
>>> On Jan 5, 2016, at 2:44 PM, Erica Sadun via swift-evolution <swift-evolution at swift.org <mailto:swift-evolution at swift.org>> wrote:
>>>
>>> Are API Design Guideline improvement discussions in scope for the Swift Evolution list and if not, where would they go?
>>>
>>> For example, the current Swift API Design Guidelines follow these rules more or less.
>>> Use imperative verb phrases for mutating methods: x.reverse(), x.sort(), x.tweak()
>>> Use noun phrases for non-mutating methods: x.distanceTo(...), idx.successor()
>>> Seems to me the rules should actually be along the lines of:
>>> Use verb phrases to declare procedural methods, whether or not they mutate an instance or just produce side effects: x.reverse(), x.sort(), x.tweak(), x.perform(), x.dispatch(), x.send()
>>> Use noun phrases to describe values returned by a functional method: x.distanceTo(y), index.successor() (This admittedly leaves further issues around other functional methods, for example, seq.separatedBySequence(seq) and int.strideTo(other: Self, step:Self.Stride), etc. )
>>> Are enhancements for API Design Guidelines an area for community involvement? Where would you start a discussion about the rules? Would modifications involve formal proposals?
>>>
>>> _______________________________________________
>>> 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>
>>
>> _______________________________________________
>> 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>
> _______________________________________________
> 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>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160105/c1451c8d/attachment.html>
More information about the swift-evolution
mailing list