on Fri Oct 14 2016, Zach Waldowski <[email protected]> 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 > [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 -- -Dave _______________________________________________ swift-evolution mailing list [email protected] https://lists.swift.org/mailman/listinfo/swift-evolution
