<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=""><br class=""><div><blockquote type="cite" class=""><div class="">On Jan 27, 2016, at 5:20 PM, Douglas Gregor <<a href="mailto:dgregor@apple.com" class="">dgregor@apple.com</a>> wrote:</div><br class="Apple-interchange-newline"><div class=""><div style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><blockquote type="cite" class=""><div class=""><br class="Apple-interchange-newline">On Jan 27, 2016, at 8:09 AM, Matthew Johnson <<a href="mailto:matthew@anandabits.com" class="">matthew@anandabits.com</a>> wrote:</div><br class="Apple-interchange-newline"><div class=""><div class="" style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;"><div class="">Doug,</div><div class=""><br class=""></div><div class="">I think this change looks great! I don’t have time to look through the full patch but did look through quite a bit. It adds clarity in the vast majority of cases I looked at. </div><div class=""><br class=""></div><div class="">It seems like with-as-separator is a good heuristic for determining when the first parameter is not essential to a good name for the fundamental operation. I agree with the comments earlier on that in these cases a label for the first parameter is the best approach.</div><div class=""><br class=""></div><div class="">I also really like that this groups methods with the same fundamental operation into overload families where they previously had independent names. This is a big win IMO.</div><div class=""><br class=""></div><div class="">There is a first-parameter-is-an-ID pattern I noticed after this change. I show a few examples here, but there are a lot more:</div><div class=""><br class="">- func trackWithTrackID(trackID: CMPersistentTrackID) -> AVAssetTrack?<br class="">+ func track(trackID trackID: CMPersistentTrackID) -> AVAssetTrack?</div><div class=""><br class=""></div><div class="">- func trackWithTrackID(trackID: CMPersistentTrackID) -> AVFragmentedAssetTrack?<br class="">+ func track(trackID trackID: CMPersistentTrackID) -> AVFragmentedAssetTrack?</div><div class=""><br class="">- func trackWithTrackID(trackID: CMPersistentTrackID) -> AVCompositionTrack?<br class="">+ func track(trackID trackID: CMPersistentTrackID) -> AVCompositionTrack?</div><div class=""><br class=""></div><div class="">- func discoverUserInfoWithUserRecordID(userRecordID: CKRecordID, completionHandler: (CKDiscoveredUserInfo?, Error?) -> Void)</div><div class=""><br class="">+ func discoverUserInfo(userRecordID userRecordID: CKRecordID, completionHandler: (CKDiscoveredUserInfo?, Error?) -> Void)</div><div class=""><br class=""></div><div class="">The first argument label `trackID` seems like it repeats type information without adding clarity. I think it would be better to just use `id` here. It seems like a candidate for heuristics as well. For example, if the type name ends in ID and the label is a suffix of the type name we could just use `id`. This is a somewhat specific pattern, but IDs are common enough that it might make sense.</div></div></div></blockquote><div class=""><br class=""></div><div class="">It affects 33 APIs; see attached patch.</div></div></div></blockquote><div><br class=""></div><div>The patch looks good!</div><br class=""><blockquote type="cite" class=""><div class=""><div style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><div class=""><br class=""></div><blockquote type="cite" class=""><div class=""><div class="" style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;"><div class="">Interestingly, in at least one case the `WithID` was the original name of the method so we did receive a simple `id` label:</div><div class=""><br class=""></div><div class="">- func parameterWithID(paramID: AudioUnitParameterID, scope: AudioUnitScope, element: AudioUnitElement) -> AUParameter?<br class="">+ func parameter(id paramID: AudioUnitParameterID, scope: AudioUnitScope, element: AudioUnitElement) -> AUParameter?</div></div></div></blockquote><div class=""><br class=""></div><div class="">What’s happening here is that we see that “ID” in “WithID” is redundant, but we don’t want to provide a first argument label of “with”, so we grab whatever followed “with”.</div></div></div></blockquote><div><br class=""></div><div>Yep, I was just noting that we already ended up with `id` in some cases.</div><br class=""><blockquote type="cite" class=""><div class=""><div style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><br class=""><blockquote type="cite" class=""><div class=""><div class="" style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;"><div class="">In another case, the method has a naked `With` at the end. Somehow `id` was used in that scenario despite the parameter name being `objectID` and the type being `NSManagedObjectID`, which aligns with my suggested naming:</div><div class=""><br class=""></div><div class="">- func newValuesForObjectWith(objectID: NSManagedObjectID, withContext context: NSManagedObjectContext) throws -> NSIncrementalStoreNode<br class="">+ func newValuesForObject(id objectID: NSManagedObjectID, withContext context: NSManagedObjectContext) throws -> NSIncrementalStoreNode</div></div></div></blockquote><div class=""><br class=""></div><div class="">This was originally newValuesForObjectWithID; again, we trimmed ID both before and after, and you’re seeing us keeping “id” because it’s better than keeping “with”.</div><br class=""><blockquote type="cite" class=""><div class=""><div class="" style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;"><div class=""><br class=""></div><div class="">A case related to that used `iDs` for array arguments: </div><div class=""><br class=""></div><div class="">- func managedObjectContextDidRegisterObjectsWithIDs(objectIDs: [NSManagedObjectID])<br class="">- func managedObjectContextDidUnregisterObjectsWithIDs(objectIDs: [NSManagedObjectID])<br class="">+ func managedObjectContextDidRegisterObjects(iDs objectIDs: [NSManagedObjectID])<br class="">+ func managedObjectContextDidUnregisterObjects(iDs objectIDs: [NSManagedObjectID])</div><div class=""><br class=""></div><div class="">I would prefer `ids` here. This seems like a pattern that would be a problem for any all-caps plural acronym or initialism so it might be good to add a heuristic for this as well.</div></div></div></blockquote><div class=""><br class=""></div><div class="">Ah, it looks like I'm handling lowercasing of plural initialisms badly. That’s a problem independent of first argument labels; thanks!</div><br class=""><blockquote type="cite" class=""><div class=""><div class="" style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;"><div class=""><br class=""></div><div class=""><br class=""></div><div class="">Here’s another interesting change:</div><div class=""><br class="">- func unionWith(s2: CIFilterShape) -> CIFilterShape<br class="">- func unionWith(r: CGRect) -> CIFilterShape<br class="">- func intersectWith(s2: CIFilterShape) -> CIFilterShape<br class="">- func intersectWith(r: CGRect) -> CIFilterShape<br class="">+ func union(with s2: CIFilterShape) -> CIFilterShape<br class="">+ func union(rect r: CGRect) -> CIFilterShape<br class="">+ func intersect(with s2: CIFilterShape) -> CIFilterShape<br class="">+ func intersect(rect r: CGRect) -> CIFilterShape</div><div class=""><br class=""></div><div class="">Why do the CGRect arguments receive a type-derived label but the CIFilterShape arguments just receive `with`? Shouldn’t these follow the same pattern?</div></div></div></blockquote><div class=""><br class=""></div>The Objective-C methods are actually named unionWith: and unionWithRect:. That first name is not following Cocoa conventions.<br class=""></div></div></blockquote><div><br class=""></div><div>Ok, that makes sense then. I didn’t think to look at the original Objective-C names. I wonder if it might be better to make these consistent though. Either discard the name if it matches the type:</div><div><br class=""></div><div><div class=""><div class=""><div class="" style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;"><div class="">func intersect(with r: CGRect) -> CIFilterShape</div><div class=""><br class=""></div><div class="">Or use the type information to create a name rather than use “with”:</div><div class=""><br class=""></div><div class="">func intersect(filterShape s2: CIFilterShape) -> CIFilterShape</div></div></div></div></div><div><br class=""></div><div>What do you think?</div><br class=""><blockquote type="cite" class=""><div class=""><div style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><div class=""><br class=""></div><span class="Apple-tab-span" style="white-space: pre;"> </span>- Doug</div><div style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><br class=""></div><div style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""></div><span id="cid:AD18B4E3-2BA6-439B-805C-79EB162534B0@Home"><universal-id.patch></span><div style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><br class=""><blockquote type="cite" class=""><div class=""><div class="" style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;"><br class=""><div class=""><blockquote type="cite" class=""><div class="">On Jan 27, 2016, at 1:50 AM, Douglas Gregor via swift-evolution <<a href="mailto:swift-evolution@swift.org" class="">swift-evolution@swift.org</a>> wrote:</div><br class="Apple-interchange-newline"><div class=""><div class="" style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;"><br class=""><div class=""><blockquote type="cite" class=""><div class="">On Jan 25, 2016, at 6:55 AM, Radosław Pietruszewski <<a href="mailto:radexpl@gmail.com" class="">radexpl@gmail.com</a>> wrote:</div><br class="Apple-interchange-newline"><div class=""><div class="" style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;"><div class="">Hello all,</div><div class=""><br class=""></div><div class="">I’m overwhelmingly *for* this proposal. I think removing needless verbosity and keeping the signal-to-noise ratio high is one of the most immediately appealing aspects of Swift, as well as a great general improvement to the programming experience.</div><div class=""><br class=""></div><div class="">And so unswiftified (yes, it’s a word now) APIs from Objective-C stick out like a sore thumb. Not only are they harder to read and write, they visually overwhelm the less verbose, information-dense Swift-first code.</div><div class=""><br class=""></div><div class="">Just like previous 1.0—2.0 attempts at bridging the gap (with NSError params being translated to Swift errors, factory methods translated to initializers, etc.), automating this will be an error-prone process, and almost bound to be a bit annoying at first, before all the glitches and poor translations are smoothed out. And yet I feel like just like the previous automated translations were overwhelmingly a great thing, so will the result of this proposal.</div><div class=""><br class=""></div><div class="">* * *</div><div class=""><br class=""></div><div class=""><div class=""></div><blockquote type="cite" class=""><div class=""> Add First Argument Labels</div><div class=""> </div><div class=""> - func enumerateObjectsWith(_: NSEnumerationOptions = [], using: (AnyObject, UnsafeMutablePointer) -> Void)</div><div class=""> + func enumerateObjects(options _: NSEnumerationOptions = [], using: (AnyObject, UnsafeMutablePointer) -> Void)</div></blockquote><br class=""></div><div class="">Good! The Guidelines recommend an explicit first parameter label for arguments with a default value, but this is a good change also for another reason, a use case not included in the Guidelines (I have more to say about this in the SE-0023 thread):</div><div class=""><br class=""></div><div class="">“Options” is the description of the parameter, not the method itself. Even if (for whatever reason!) `options` didn’t have a default value and the word “Options” wasn’t omitted in the translation,</div><div class=""><br class=""></div><div class=""> enumerateObjects(options: …)</div><div class=""><br class=""></div><div class="">would be clearer than</div><div class=""><br class=""></div><div class=""> enumerateObjectsWithOptions(…)</div><div class=""><br class=""></div><div class="">It’s not even about the extra word, about the four useless characters, it’s simply that “WithOptions” doesn’t describe the operation at all. It’s a word that conveys no information (“with”), and “options”, which describes the first parameter. In Objective-C, there’s no such thing as parameter labels, it’s all one name, so “With” is used as a separator. But in Swift, making the first parameter’s label explicit just makes more sense.</div></div></div></blockquote><div class=""><br class=""></div><div class="">That’s an interesting thought! If “with” is truly used as a convention for separating the description of the operation from the description of the first parameter, that’s something that can be codified in the Clang importer. I was curious, so I hacked it up. Here’s a diff of the Cocoa APIs that shows what things would look like if we treated “with” as a separator:</div><div class=""><br class=""></div><div class=""><span class="Apple-tab-span" style="white-space: pre;"> </span><a href="https://github.com/apple/swift-3-api-guidelines-review/pull/5/files" class="">https://github.com/apple/swift-3-api-guidelines-review/pull/5/files</a></div><div class=""><br class=""></div><div class="">It’s a diff against SE-0005, and it introduces a significant number of first argument labels. Indeed, you’ll need to grab the patch to see them all:</div><div class=""><br class=""></div><div class=""><span class="Apple-tab-span" style="white-space: pre;"> </span><a href="https://github.com/apple/swift-3-api-guidelines-review/pull/5.patch" class="">https://github.com/apple/swift-3-api-guidelines-review/pull/5.patch</a></div><div class=""><br class=""></div><div class="">A brief survey shows that some cases seem to be lining up with the guideline proposals that have been under discussion. For example, the patch includes:</div><div class=""><br class=""></div><div class=""><div class="">- func fillWith(blendMode: CGBlendMode, alpha: CGFloat)</div><div class="">- func strokeWith(blendMode: CGBlendMode, alpha: CGFloat)</div><div class="">+ func fill(blendMode blendMode: CGBlendMode, alpha: CGFloat)</div><div class="">+ func stroke(blendMode blendMode: CGBlendMode, alpha: CGFloat)</div><div class=""><br class=""></div></div><div class=""><div class="">- func encodeWith(aCoder: Coder)</div><div class="">+ func encode(coder aCoder: Coder)</div><div class=""><br class=""></div><div class="">which you might recognize, because it’s the example you used:</div><div class=""><br class=""></div></div><blockquote type="cite" class=""><div class=""><div class="" style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;"><div class="">And with that in mind, I object to these translations:</div><div class=""><br class=""></div><div class=""><div class=""> func fillWith(_: CGBlendMode, alpha: CGFloat)</div><div class=""> func strokeWith(_: CGBlendMode, alpha: CGFloat)</div><div class=""> func encodeWith(_: Coder)</div></div><div class=""><br class=""></div><div class="">Even though these don’t have default values, I believe this version to be clearer and make more sense, even if slightly more verbose:</div><div class=""><br class=""></div><div class=""> func fill(blendMode: CGBlendMode, alpha: CGFloat)</div><div class=""> func stroke(blendMode: CGBlendMode, alpha: CGFloat)</div><div class=""> func encode(coder: Coder)</div></div></div></blockquote><br class=""></div><div class="">Another random interesting example I encountered:</div><div class=""><br class=""></div><div class=""><div class="">- func addArcWithCenter(center: CGPoint, radius: CGFloat, startAngle: CGFloat, endAngle: CGFloat, clockwise: Bool)</div><div class="">+ func addArc(center center: CGPoint, radius: CGFloat, startAngle: CGFloat, endAngle: CGFloat, clockwise: Bool)</div><div class=""><br class=""></div></div><div class="">which seems to match the idea behind Erica’s "semantic relationship between the parameters is stronger than their relation to the operation” (or Paul Cantrell’s similar notion of "the direct object is several args taken together”, which feels more in line with the way the API guidelines are written).</div><div class=""><br class=""></div><div class="">There’s also this:</div><div class=""><br class=""></div><div class=""><div class="">- func tracksWithMediaType(mediaType: String) -> [AVMovieTrack]</div><div class="">+ func tracks(mediaType mediaType: String) -> [AVMovieTrack]</div><div class=""><br class=""></div><div class="">- func tracksWithMediaCharacteristic(mediaCharacteristic: String) -></div><div class="">+ func tracks(mediaCharacteristic mediaCharacteristic: String) -> [AVMovieTrack]</div><div class=""><br class=""></div></div><div class="">which feels reminiscent of Paul’s “resource” example:</div><div class=""><br class=""></div><div class=""><div class="" style="margin: 0px; font-size: 10.5px; line-height: normal; font-family: Menlo; color: rgb(88, 126, 168);"><span class=""> </span>service<span class="">.</span>resource<span class="">(</span><span class="" style="color: rgb(132, 62, 100);">"/foo"</span><span class="">)</span></div><div class="" style="margin: 0px; font-size: 10.5px; line-height: normal; font-family: Menlo;"> <span class="" style="color: rgb(88, 126, 168);">service</span>.<span class="" style="color: rgb(88, 126, 168);">resource</span>(absoluteURL: <span class="" style="color: rgb(132, 62, 100);">"<a href="http://bar.com/" class="">http://bar.com</a>"</span>)</div><div class="" style="margin: 0px; font-size: 10.5px; line-height: normal; font-family: Menlo;"> <span class="" style="color: rgb(88, 126, 168);">service</span>.<span class="" style="color: rgb(88, 126, 168);">resource</span>(absoluteURL: <span class="" style="color: rgb(88, 126, 168);">NSURL</span>(string: <span class="" style="color: rgb(132, 62, 100);">"<a href="http://bar.com/" class="">http://bar.com</a>"</span>))</div></div><div class=""><br class=""></div><div class="">where (I think) the argument is that the various methods should all have the same base name because they’re all returning “tracks” or a “resource”, respectively.</div><div class=""><br class=""></div><div class="">There is a ton of data in that patch. I’d be interested to hear whether the resulting Cocoa APIs feel better in Swift—are they following the evolving set of guidelines for first argument labels that are under discussion, and are the resulting APIs clearer/more Swifty? What specific APIs work well and where does this “with-as-separator” heuristic break down?</div><div class=""><br class=""></div><div class=""><span class="Apple-tab-span" style="white-space: pre;"> </span>- Doug</div><div class=""><br class=""></div><br class=""></div>_______________________________________________<br class="">swift-evolution mailing list<br class=""><a href="mailto:swift-evolution@swift.org" class="">swift-evolution@swift.org</a><br class=""><a href="https://lists.swift.org/mailman/listinfo/swift-evolution" class="">https://lists.swift.org/mailman/listinfo/swift-evolution</a></div></blockquote></div></div></div></blockquote></div></div></blockquote></div><br class=""></body></html>