<html><head><meta http-equiv="Content-Type" content="text/html charset=utf-8"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><div><br class=""><blockquote type="cite" class=""><div class=""><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><div class=""><blockquote type="cite" class=""><div class=""><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><div class="">Ah, interesting!</div><div class=""><br class=""></div><div class="">I definitely see the rationale for this. Calling a method like `tracks` seems a bit confusing, it doesn’t capture the intent at all. The ObjC-convention version, say, `tracksWithMediaType(…)`, though less clear, makes a better job at this.</div><div class=""><br class=""></div><div class="">I can see more methods of this kind in the diff, and they seem to benefit the most.</div><div class=""><br class=""></div><div class="">I mentioned this before, but the way I would prefer this named is `findTracks(…)`, and skip the “with” in the name. The intent is captured better than the original, we start with a verb, and the method name is separated from its parameters. But obviously this is unlikely to work as an automated translation.</div><div class=""><br class=""></div><div class="">Having said that, a lot of the changes seem like a step back:</div><div class=""><br class=""></div><div class=""><br class=""><blockquote type="cite" class=""> func highlight(level val: CGFloat) -> NSColor?<span class="Apple-tab-span" style="white-space:pre"> </span><span class="Apple-tab-span" style="white-space:pre"> </span> func highlight(level val: CGFloat) -> NSColor?<br class="">- func shadow(level val: CGFloat) -> NSColor?<span class="Apple-tab-span" style="white-space:pre"> </span><span class="Apple-tab-span" style="white-space:pre"> </span>+ func shadowWithLevel(val: CGFloat) -> NSColor?</blockquote><br class=""></div><div class="">Inconsistency. Highlight analyzed as as a verb, shadow as a noun, even though those are obviously related.</div></div></div></blockquote><div class=""><br class=""></div><div class="">Yes, this is an inconsistency we would need to deal with via NS_SWIFT_NAME. “highlight” is acting as an adjective here, although it’s predominantly a verb in Cocoa APIs.</div></div></div></div></blockquote><div><br class=""></div><div>True, but it would seem preferable to me to choose an approach for which having to fix up a name with NS_SWIFT_NAME is a rare occurrence.</div><br class=""><blockquote type="cite" class=""><div class=""><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><div class=""><blockquote type="cite" class=""><div class=""><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><div class=""><br class=""></div><div class=""><blockquote type="cite" class="">- func blendedColor(fraction fraction: CGFloat, of color: NSColor) -> NSColor?<span class="Apple-tab-span" style="white-space:pre"> </span><span class="Apple-tab-span" style="white-space:pre"> </span>+ func blendedColorWithFraction(fraction: CGFloat, of color: NSColor) -> NSColor?</blockquote><br class=""></div><div class="">This doesn’t seem like an improvement. “fraction” and “color” seem very much like parameters to be separated from the name.</div></div></div></blockquote><div class=""><br class=""></div><div class="">Note that this is the intent of the change, however: blendedColor is a noun phrase describing the result, and “withFraction” is a characteristic of the resulting color.</div></div></div></div></blockquote><div><br class=""></div><div>I understand; I just find it a much less compelling example for Jordan’s approach than something like the previously mentioned “tracks”.</div><div><br class=""></div><div>Perhaps the way to differentiate further cases where “with” in the name is useful is: methods that you can imagine being called “findFoo”, and take some argument as a search condition, but without it, only a single noun remains.</div><div><br class=""></div><div>Looking through the diff, methods like these:</div><div><br class=""></div></div><blockquote style="margin: 0 0 0 40px; border: none; padding: 0px;" class=""><div><div>track(trackID trackID: CMPersistentTrackID) -> AVAssetTrack?</div></div><div><div>func tracks(mediaCharacteristic mediaCharacteristic: String) -> [AVFragmentedAssetTrack]</div></div><div><div>class func devices(mediaType mediaType: String!) -> [AnyObject]!</div></div><div><div>class func defaultDevice(mediaType mediaType: String!) -> AVCaptureDevice!</div></div><div><div>func connection(mediaType mediaType: String!) -> AVCaptureConnection!</div></div><div><div>func mutableTrack(compatibleWith track: AVAssetTrack) -> AVMutableCompositionTrack?<span class="Apple-tab-span" style="white-space:pre"> </span></div></div></blockquote><div><div><br class=""></div><div>Bother me the most. But a lot others, I feel like they’re worse off for having “with” back in the name</div><div><br class=""></div><blockquote type="cite" class=""><div class=""><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><div class=""><blockquote type="cite" class=""><div class=""><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><div class=""><blockquote type="cite" class="">- class func availableColorSpaces(model model: NSColorSpaceModel) -> [NSColorSpace]<span class="Apple-tab-span" style="white-space:pre"> </span><span class="Apple-tab-span" style="white-space:pre"> </span>+ class func availableColorSpacesWith(model: NSColorSpaceModel) -> [NSColorSpace]</blockquote><blockquote type="cite" class=""> func indexOfItem(objectValue object: AnyObject) -> Int<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>+ func indexOfItemWithObjectValue(object: AnyObject) -> Int</blockquote><br class=""></div><div class="">Same…</div></div></div></blockquote><div class=""><br class=""></div>With the same answer: both start with noun phrases describing the result, so the “with” is acting more like “having”, indicating that the parameter is describing the characteristics of the result.</div><div class=""><br class=""></div><div class=""><blockquote type="cite" class=""><div class=""><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><div class=""><br class=""></div><div class=""><br class=""><blockquote type="cite" class="">- func reviewUnsavedDocuments(alertTitle title: String?, cancellable: Bool, delegate: AnyObject?, didReviewAllSelector: Selector, contextInfo: UnsafeMutablePointer<Void>)<span class="Apple-tab-span" style="white-space:pre"> </span><span class="Apple-tab-span" style="white-space:pre"> </span>+ func reviewUnsavedDocumentsWithAlertTitle(title: String?, cancellable: Bool, delegate: AnyObject?, didReviewAllSelector: Selector, contextInfo: UnsafeMutablePointer<Void>)</blockquote><br class=""></div><div class="">This definitely seem like a step back, “reviewUnsavedDocuments” works really well as a name, without the sort of confusion that the “tracks” mentioned above has.</div></div></div></blockquote><div class=""><br class=""></div><div class="">Somehow, “review” wasn’t in my list of verbs. I’ll fix this.</div></div></div></div></blockquote><div><br class=""></div><div>Another one:</div><div><br class=""></div><div>func invalidateLayoutWith(context: NSCollectionViewLayoutInvalidationContext)</div><div>+ func swapWithMark(sender: AnyObject?)</div><br class=""><blockquote type="cite" class=""><div class=""><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><div class=""><br class=""><blockquote type="cite" class=""><div class=""><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><div class=""><blockquote type="cite" class="">- class func mouseEvent(type type: NSEventType, location: Point, modifierFlags flags: NSEventModifierFlags, timestamp time: TimeInterval, windowNumber wNum: Int, context: NSGraphicsContext?, eventNumber eNum: Int, clickCount cNum: Int, pressure: Float) -> NSEvent?<span class="Apple-tab-span" style="white-space:pre"> </span><span class="Apple-tab-span" style="white-space:pre"> </span></blockquote><blockquote type="cite" class="">+ class func mouseEventWith(type: NSEventType, location: Point, modifierFlags flags: NSEventModifierFlags, timestamp time: TimeInterval, windowNumber wNum: Int, context: NSGraphicsContext?, eventNumber eNum: Int, clickCount cNum: Int, pressure: Float) -> NSEvent?</blockquote><br class=""></div><div class="">This one’s weird. “With” was added, but without “type” in the name.</div></div></div></blockquote><div class=""><br class=""></div><div class="">“type” is redundant with the type info, so it has been pruned.</div></div></div></div></blockquote><div><br class=""></div><div>But is “mouseEventWith” as a name actually desirable?</div></div><br class=""><div class="">* * *</div><div class=""><br class=""></div><div class="">Another thing that bothers me is how this makes method families have different names:</div><div class=""><br class=""><blockquote type="cite" class="">- func indexOfItem(title aTitle: String) -> Int<span class="Apple-tab-span" style="white-space:pre"> </span><span class="Apple-tab-span" style="white-space:pre"> </span>+ func indexOfItemWithTitle(aTitle: String) -> Int<br class="">- func indexOfItem(tag aTag: Int) -> Int<span class="Apple-tab-span" style="white-space:pre"> </span><span class="Apple-tab-span" style="white-space:pre"> </span>+ func indexOfItemWithTag(aTag: Int) -> Int<br class="">- func indexOfItem(representedObject object: AnyObject) -> Int<span class="Apple-tab-span" style="white-space:pre"> </span><span class="Apple-tab-span" style="white-space:pre"> </span>+ func indexOfItemWithRepresentedObject(object: AnyObject) -> Int<br class="">- func indexOfItem(submenu submenu: NSMenu?) -> Int<span class="Apple-tab-span" style="white-space:pre"> </span><span class="Apple-tab-span" style="white-space:pre"> </span>+ func indexOfItemWithSubmenu(submenu: NSMenu?) -> Int<br class="">- func indexOfItem(target target: AnyObject?, andAction actionSelector: Selector) -> Int<span class="Apple-tab-span" style="white-space:pre"> </span><span class="Apple-tab-span" style="white-space:pre"> </span>+ func indexOfItemWithTarget(target: AnyObject?, andAction actionSelector: Selector) -> Int</blockquote></div><div class=""><br class=""></div><div class="">I think it would be desirable for this, being essentially a few versions of the same method, just taking different arguments, to have a single name.</div><div class=""><br class=""></div><div class="">This also passes the “you could imagine the name starting with ‘find’” test.</div><div class=""><br class=""></div><div class="">* * *</div><div class=""><br class=""></div><div class=""><br class=""><blockquote type="cite" class=""> func smartMagnify(event event: NSEvent)<span class="Apple-tab-span" style="white-space:pre"> </span><span class="Apple-tab-span" style="white-space:pre"> </span>+ func smartMagnifyWith(event: NSEvent)<br class=""> @available(OSX 10.6, *)<span class="Apple-tab-span" style="white-space:pre"> </span><span class="Apple-tab-span" style="white-space:pre"> </span> @available(OSX 10.6, *)<br class="">- func touchesBegan(event event: NSEvent)<span class="Apple-tab-span" style="white-space:pre"> </span><span class="Apple-tab-span" style="white-space:pre"> </span>+ func touchesBeganWith(event: NSEvent)<br class=""> @available(OSX 10.6, *)<span class="Apple-tab-span" style="white-space:pre"> </span><span class="Apple-tab-span" style="white-space:pre"> </span> @available(OSX 10.6, *)<br class="">- func touchesMoved(event event: NSEvent)<span class="Apple-tab-span" style="white-space:pre"> </span><span class="Apple-tab-span" style="white-space:pre"> </span>+ func touchesMovedWith(event: NSEvent)<br class=""> @available(OSX 10.6, *)<span class="Apple-tab-span" style="white-space:pre"> </span><span class="Apple-tab-span" style="white-space:pre"> </span> @available(OSX 10.6, *)<br class="">- func touchesEnded(event event: NSEvent)<span class="Apple-tab-span" style="white-space:pre"> </span><span class="Apple-tab-span" style="white-space:pre"> </span>+ func touchesEndedWith(event: NSEvent)<br class=""> @available(OSX 10.6, *)<span class="Apple-tab-span" style="white-space:pre"> </span><span class="Apple-tab-span" style="white-space:pre"> </span> @available(OSX 10.6, *)<br class="">- func touchesCancelled(event event: NSEvent)<span class="Apple-tab-span" style="white-space:pre"> </span><span class="Apple-tab-span" style="white-space:pre"> </span>+ func touchesCancelledWith(event: NSEvent)<br class=""> @available(OSX 10.8, *)<span class="Apple-tab-span" style="white-space:pre"> </span><span class="Apple-tab-span" style="white-space:pre"> </span> @available(OSX 10.8, *)<br class="">- func quickLook(event event: NSEvent)<span class="Apple-tab-span" style="white-space:pre"> </span><span class="Apple-tab-span" style="white-space:pre"> </span>+ func quickLookWith(event: NSEvent)<br class=""> @available(OSX 10.10.3, *)<span class="Apple-tab-span" style="white-space:pre"> </span><span class="Apple-tab-span" style="white-space:pre"> </span> @available(OSX 10.10.3, *)<br class="">- func pressureChange(event event: NSEvent)<span class="Apple-tab-span" style="white-space:pre"> </span><span class="Apple-tab-span" style="white-space:pre"> </span>+ func pressureChangeWith(event: NSEvent)</blockquote><br class=""></div><div class="">Not digging this either. Passing NSEvent here feels like passing “sender” — an idiom that seems in no need of adding a “With” suffix to the method name…</div><div class=""><br class=""></div><div class=""><br class=""></div><div class="">Best,</div><div class="">— Radek</div></body></html>