[swift-evolution] [Guidelines, First Argument Labels]: Prepositions inside the parens

[Ricardo Parada]

Hi all,
I reviewed the changes and I feel positive about them in general.  For whatever it’s worth, I like them.  
There were some changes in Core Data for example where the with preposition is used in other parameters in addition to the first one.  I thought only the first parameter label was to use the with preposition. For example, I think I would remove the forObjectWith and the withContext labels and keep objectID and context as the labels:
+  func newValue(forRelationship relationship: NSRelationshipDescription, forObjectWith objectID: NSManagedObjectID, withContext context: NSManagedObjectContext?) throws -> AnyObject
Thanks
Ricardo Parada


> Hi everybody,
> 
> Having looked at some examples, the API guidelines working group members
> that were present this morning agreed we really want prepositions inside
> the parentheses of method calls.
> 
> Here are some results for the importer; we're still tuning some of the
> heuristics but overall we feel very good about the preposition
> placement:
>   
>   https://github.com/apple/swift-3-api-guidelines-review/commit/da7e512cf75688e6da148dd2a8b27ae9efcb8821?diff=split <https://github.com/apple/swift-3-api-guidelines-review/commit/da7e512cf75688e6da148dd2a8b27ae9efcb8821?diff=split>
> 
> Note that this is not final wording, but here are the guidelines we're
> working with for first argument labels:
> 
> A. Try to form a grammatical phrase including the first argument and
>    describing the primary semantics at the call site.
> 
> B. The first argument gets a label when and only when:
> 
>    1. It does not form part of a grammatical phrase describing the
>       primary semantics.  For example,
>       ```
>       x.dismiss(animated: y)
>       ```
>       [more examples needed]
>       Note that parameters with defaults never describe the primary
>       semantics. so are always labeled.
>       ```
>       func invert(options options: SomeOptionSet = []) // yes
>       func invert(_ options: SomeOptionSet = [])       // no
>       ```
> 
>    2. The method is a factory method; such calls should mirror
>       initializers, with no preposition.  For example,
>       ```
>       let x = UIColor(red: r, green: g, blue: b)
>       let y = monitor.makeColor(red: r, green: g, blue: b)
>       ```
> 
>    3. It is part of a prepositional phrase
> 
>      a. The label normally starts with the preposition. 
>         For example, 
>         ```
>         x.move(from: a, to: b)
>         x.loadValues(forKeys: ["fox", "box", "lox"])
>         ```
>      b. ...unless the preposition would break a very tight association
>         between parameters:
>         ```
>         x.moveTo(x: a, y: b)
>         ```
>         [encourage grouping parameters into higher-level concepts,
>         e.g. Point, in these cases]
>       
> 
> 
> Feedback most welcome, of course.
> -- 
> -Dave

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160213/c1952f76/attachment.html>