[swift-evolution] [Discussion] API Guidelines

[Charlie Monroe]

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