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 [email protected] 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 > [email protected] > https://lists.swift.org/mailman/listinfo/swift-evolution _______________________________________________ swift-evolution mailing list [email protected] https://lists.swift.org/mailman/listinfo/swift-evolution
