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

[Jacob Bandes-Storch]

I think I like this direction in general. It feels more natural to have the
preposition in the label than outside the parenthesis (and it's worth
keeping the preposition because it improves clarity in most cases).

Here are some strange examples which need tweaking:

     + func accountType(withAccountTypeIdentifier typeIdentifier: String!)
-> ACAccountType!

Probably should just be "withIdentifier".

     + func comparePositionInDecodeOrderWithPosition(of cursor:
AVSampleCursor) -> ComparisonResult

I would suggest comparePositionInDecodeOrder(withPositionOf cursor:
AVSampleCursor). Tricky because there are two prepositions.

      func componentsPassingTest(testHandler: (AVAudioUnitComponent,
UnsafeMutablePointer<ObjCBool>) -> Bool) -> [AVAudioUnitComponent]
 -    func componentsMatching(desc: AudioComponentDescription) ->
[AVAudioUnitComponent]
 +   func components(matching desc: AudioComponentDescription) ->
[AVAudioUnitComponent]

Should "passingTest" become the first label?

     -  class func exportPresetsCompatibleWith(asset: AVAsset) -> [String]
     +  class func exportPresetsCompatible(withAsset asset: AVAsset) ->
[String]

This is not an improvement. I'd suggest exportPresets(compatibleWith asset:
AVAsset), but that doesn't really fit under the current rules. Maybe a
special case for [noun][adjective][preposition]?

    -  func compatibleTrackFor(compositionTrack: AVCompositionTrack) ->
AVAssetTrack?
    +  func compatibleTrack(forCompositionTrack compositionTrack:
AVCompositionTrack) -> AVAssetTrack?

Does this indicate that some other suffix-matching rules are no longer
being applied? I'd have expected compatibleTrack(for compositionTrack:
AVCompositionTrack). I also see other examples like
renewCredentials(forAccount account: ACAccount, ...).

      func createSampleBufferFor(request: AVSampleBufferRequest) ->
CMSampleBuffer

Why wasn't this changed?

      -  class func typeOf(property property: String!) -> ABPropertyType
      +  class func type(ofProperty property: String!) -> ABPropertyType

I don't really like either of these. Maybe we need special rules for "of" ?


If anyone else is worried about special cases, I just looked this up:
there's a clang __attribute__((swift_name("x"))), or NS_SWIFT_NAME(x),
which can be used to expose Obj-C methods to Swift with particular custom
names.

Jacob

On Tue, Feb 9, 2016 at 11:18 AM, Dave Abrahams via swift-evolution <
swift-evolution at swift.org> wrote:

>
> 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
>
> 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
>
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160209/961f9332/attachment.html>