[swift-evolution] [Discussion] API Guidelines

[Dave Abrahams]

on Fri Oct 14 2016, Zach Waldowski <swift-evolution at swift.org> wrote:

> The base name of the function describes its core purpose.
>
> There is no ambiguity instructing an Array to "append" something, but
> there is context needed: "what are we appending? The contents of the
> newElements parameter." 

That's because there's a distinction between appending the newElements
paramter (as a single new element on an array of Any) and appending its
elements.

> But there is ambiguity asking URL to "give me a new URL by
> appending". Appending what?

Actually, no, you are passing an argument.  That's what's being
appended.  If there's only one reasonable way to append a String to a
URL, no noun should be needed.  If there's some ambiguity as to the
semantics, that might justify the "pathComponent:" label.

> Similarly, telling a collection to "replace". Replace what?
>
> A rule of thumb my team has applied is to put the parameter parens where
> you would have put `with` in ObjC. This is instructive for your
> questions as well. "URLByAppendingWithPathComponent" and
> "replaceWithSubrange" wouldn't make sense, but "appendWithContentsOf"
> does.
>
> Cheers!
>   Zachary Waldowski
>   zach at waldowski.me
>
> On Thu, Oct 13, 2016, at 10:30 PM, Charlie Monroe via swift-evolution
> wrote:
>> Hi there,
>> 
>> I am really grateful for the API guidelines that were created as part of
>> Swift 3, however, I'm having trouble with distinguishing which part of
>> the method name should be already an argument. To illustrate this, here
>> are two examples:
>> 
>> // On Array
>> public mutating func append(contentsOf newElements: S)
>> 
>> // On Foundation.URL
>> public func appendingPathComponent(_ pathComponent: String) -> URL
>> 
>> 
>> Is there a particular reason why it's not
>> 
>> public func appending(pathComponent: String) -> URL
>> 
>> ?
>> 
>> In my opinion the entire stdlib and Foundation is full of such
>> discrepancies which make it hard to decide when you name your own methods
>> since there are preceding cases in the language itself (or Foundation)
>> that go both ways.
>> 
>> The same goes for why don't the replace methods (this is on String)
>> follow the same - when there is append(contentsOf:):
>> 
>> public mutating func replaceSubrange(_ bounds: ClosedRange<String.Index>,
>> with newElements: String)
>> 
>> instead of
>> 
>> public mutating func replace(subrange bounds: ClosedRange<String.Index>,
>> with newElements: String)
>> 
>> 
>> 
>> I know there was an extensive discussion about this here when the stdlib
>> names were discussed. And given that these would be breaking changes, I
>> don't necessarily want to start a lengthy discussion about renaming those
>> again - I'm just wondering what are the reasons behind this and what
>> should be the correct naming conventions.
>> 
>> Thanks!
>> 
>> Charlie
>> _______________________________________________
>> swift-evolution mailing list
>> swift-evolution at swift.org
>> https://lists.swift.org/mailman/listinfo/swift-evolution
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution

-- 
-Dave