[swift-evolution] When to use argument labels (a new approach)

[Tino Heth]

I'm quite certain that it isn't feasible to construct a set of rules that always ensure "perfect" labeling (therefore I'm not that happy that Swift has several different rules for label handling that push users towards a choice that is quite common, but doesn't fit in a significant amount of cases — but that's another topic :)

My personal guidelines are:
- When a method has a "target" object, this should be the first parameter and have no label ("addSubview", "moveToPoint").
- The same is true when there are several targets (many examples for this a global functions like "max", "add" — and vararg arguments, which fit in fine).
- If the target is a combination of parameters, each parameter deserves its own label ("moveTo(x: 1, y: 2)" is a perfect example; I consider the target to be a tuple of two numbers)

Based on this, there are some rules of thumb:
- Parameters that specify how something should be done always have a label ("popViewController(animated: Bool)": "self" is the only target, "animated" is just a detail)
- Command names consisting of more than three words have a bad smell:
verb, [adjective/adverb], noun is all you need for clear instructions.
I wrote "command" instead of "method" on purpose, because query-like statements often need more words. Example: "isDescendantOfView(container)"
Methods like
func exchangeSubviewAtIndex(_ index1: Int <https://developer.apple.com/library/ios/documentation/Swift/Reference/Swift_Int_Structure/index.html#//apple_ref/swift/struct/s:Si>,
         withSubviewAtIndex index2: Int <https://developer.apple.com/library/ios/documentation/Swift/Reference/Swift_Int_Structure/index.html#//apple_ref/swift/struct/s:Si>)
still fit into that scheme, as they look like a shortcut combining a query with a command.

Tino
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160203/3cf512b6/attachment.html>