[swift-evolution] [Discussion] API Guidelines

[Zach Waldowski]

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." But there is ambiguity asking URL to "give me a
new URL by appending". Appending what? 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