Clarification about the Swift API Design Guide - Initializer and factory methods calls

Using Swift
1

Swift API Design Guide <https://swift.org/documentation/api-design-guidelines&gt; says :

   The first argument to initializer and factory methods calls should not form a phrase starting with the base name

Specially, it advises us against writing things like :

   let foreground = Color(havingRGBValuesRed: 32, green: 64, andBlue: 128)
   let newPart = factory.makeWidget(havingGearCount: 42, andSpindleCount: 14)
   let ref = Link(to: destination)

But in UIKit, the Swift Standard Library or in Foundation, we find code like :

    struct Array<T> {
        // ...
        init(repeating repeatedValue: Array.Element, count: Int)
    }

    struct Data {
        // ...
        init(referencing reference: NSData)
    }

    class UIImage {
        // …
        init?(named name: String, in bundle: Bundle?, compatibleWith traitCollection: UITraitCollection?)
    }

I understand that some UIKit methods inherit their ObjC declarations like imageNamed:inBundle:compatibleWithTraitCollection: <imageNamed:inBundle:compatibleWithTraitCollection: | Apple Developer Documentation.
But what about Foundation and the Swift Standard Library ?

I agree that the initializers respect the Swift fundamentals : clean, short, readable, and consistent.
But the guide seems to be clear about it : we should not write such things.

Could someone shed some light on this point for me ? The subtlety about it.

2

I didn’t write the guidelines but i never really felt
Array(repeating:count:) was weird, you have two arguments, they need to be
distinguished, and repeating is actually shorter than repeatedValue.

···

On Tue, Jan 9, 2018 at 12:09 PM, Gaétan Zanella via swift-users < swift-users@swift.org> wrote:

Swift API Design Guide
<https://swift.org/documentation/api-design-guidelines&gt; says :

> The first argument to initializer and factory methods calls should
not form a phrase starting with the base name

Specially, it advises us against writing things like :

> let foreground = Color(havingRGBValuesRed: 32, green: 64,
andBlue: 128)
> let newPart = factory.makeWidget(havingGearCount: 42,
andSpindleCount: 14)
> let ref = Link(to: destination)

But in UIKit, the Swift Standard Library or in Foundation, we find code
like :

    struct Array<T> {
        // ...
        init(repeating repeatedValue: Array.Element, count: Int)
    }

    struct Data {
        // ...
        init(referencing reference: NSData)
    }

    class UIImage {
        // …
        init?(named name: String, in bundle: Bundle?, compatibleWith
traitCollection: UITraitCollection?)
    }

I understand that some UIKit methods inherit their ObjC declarations like
imageNamed:inBundle:compatibleWithTraitCollection:
<imageNamed:inBundle:compatibleWithTraitCollection: | Apple Developer Documentation;
.
But what about Foundation and the Swift Standard Library ?

I agree that the initializers respect the Swift fundamentals : clean,
short, readable, and consistent.
But the guide seems to be clear about it : we should not write such things.

Could someone shed some light on this point for me ? The subtlety about it.

_______________________________________________
swift-users mailing list
swift-users@swift.org
https://lists.swift.org/mailman/listinfo/swift-users

3

I think the advice is really to avoid unnecessary "helper" words in the names

    let foreground = Color(havingRGBValuesRed: 32, green: 64, andBlue: 128)
"Having" and "and" are unnecessary... Should be
    let foreground = Color(red: 32, green: 64, blue: 128)

    let newPart = factory.makeWidget(havingGearCount: 42, andSpindleCount: 14)
Again, "having" and "and" are not needed... Should be
    let newPart = factory.makeWidget(gearCount: 42, spindleCount: 14)
Or...
    let newPart = factory.makeWidget(gears: 42, spindles: 14)

    let ref = Link(to: destination)
In this case, "to" is kinda useful. Though it might be better if the label names the thing.
    let ref = Link(url: destination)
Or...
    let ref = Link(target: destination)

···

--
C. Keith Ray

* What Every Programmer Needs To… by C. Keith Ray [PDF/iPad/Kindle] <- buy my book?
* http://www.thirdfoundationsw.com/keith_ray_resume_2014_long.pdf
* http://agilesolutionspace.blogspot.com/

On Jan 9, 2018, at 12:10 PM, Kelvin Ma via swift-users <swift-users@swift.org> wrote:

I didn’t write the guidelines but i never really felt Array(repeating:count:) was weird, you have two arguments, they need to be distinguished, and repeating is actually shorter than repeatedValue.

On Tue, Jan 9, 2018 at 12:09 PM, Gaétan Zanella via swift-users <swift-users@swift.org> wrote:
Swift API Design Guide says :

> The first argument to initializer and factory methods calls should not form a phrase starting with the base name

Specially, it advises us against writing things like :

> let foreground = Color(havingRGBValuesRed: 32, green: 64, andBlue: 128)
> let newPart = factory.makeWidget(havingGearCount: 42, andSpindleCount: 14)
> let ref = Link(to: destination)

But in UIKit, the Swift Standard Library or in Foundation, we find code like :

    struct Array<T> {
        // ...
        init(repeating repeatedValue: Array.Element, count: Int)
    }

    struct Data {
        // ...
        init(referencing reference: NSData)
    }

    class UIImage {
        // …
        init?(named name: String, in bundle: Bundle?, compatibleWith traitCollection: UITraitCollection?)
    }

I understand that some UIKit methods inherit their ObjC declarations like imageNamed:inBundle:compatibleWithTraitCollection:.
But what about Foundation and the Swift Standard Library ?

I agree that the initializers respect the Swift fundamentals : clean, short, readable, and consistent.
But the guide seems to be clear about it : we should not write such things.

Could someone shed some light on this point for me ? The subtlety about it.

_______________________________________________
swift-users mailing list
swift-users@swift.org
https://lists.swift.org/mailman/listinfo/swift-users

_______________________________________________
swift-users mailing list
swift-users@swift.org
https://lists.swift.org/mailman/listinfo/swift-users