Swift API Design Guidelinesby Apple Inc.

Sai Li @ Yowoo Tech. 2016 / 11 / 11

Reference

• Apple Swift API Design Guidelines

• Function Naming In Swift 3

Fundamentals

• Clarity at the point of use

• Clarity is more important than brevity

• Write a documentation comment

Clarity at the point of use

Clarity at the point of use

• Declared once but used repeatedly

Clarity at the point of use

• Declared once but used repeatedly

• Clear and Concise

Clarity at the point of use

• Declared once but used repeatedly

• Clear and Concise

• When evaluating a design, reading a declaration is seldom sufficient; always examine a use case to make sure it looks clear in context.

Clarity is more important than brevity

Clarity is more important than brevity

• non-goal to enable the smallest possible code fewest characters

Clarity is more important than brevity

• non-goal to enable the smallest possible code fewest characters

• Brevity: a side-effect of the strong type system and features

Write a documentation comment

Write a documentation comment

• Every declaration

Write a documentation comment

• Every declaration

• Don’t put it off

Naming

Promote Clear Usage• Include all the words needed to avoid ambiguity

Promote Clear Usage• Include all the words needed to avoid ambiguity

Promote Clear Usage• Include all the words needed to avoid ambiguity

Omit needless words• Every word in a name should convey salient

information at the use site

Omit needless words• Every word in a name should convey salient

information at the use site

redundant

Name variables, parameters, and associated types according to their Roles• rather than their type

Name variables, parameters, and associated types according to their Roles• rather than their type

Name variables, parameters, and associated types according to their Roles• rather than their type

Name variables, parameters, and associated types according to their Roles• rather than their type

Name variables, parameters, and associated types according to their Roles• rather than their type

Sometimes….

Compensate for weak type information

Compensate for weak type information• NSObject, Any, AnyObject, Int or String…

Compensate for weak type information• NSObject, Any, AnyObject, Int or String…

• precede each weakly typed parameter with a noun describing its role

Compensate for weak type information• NSObject, Any, AnyObject, Int or String…

• precede each weakly typed parameter with a noun describing its role

Compensate for weak type information• NSObject, Any, AnyObject, Int or String…

• precede each weakly typed parameter with a noun describing its role

Compensate for weak type information• NSObject, Any, AnyObject, Int or String…

• precede each weakly typed parameter with a noun describing its role

Grammatical English Phrases

Sometimes…

Factory method & init()

Factory method & init()• “make”:

Factory method & init()• “make”:

• x.makeIterator()

Factory method & init()• “make”:

• x.makeIterator()

• x.makeWidget(cogCount: 47)

Factory method & init()• “make”:

• x.makeIterator()

• x.makeWidget(cogCount: 47)

Factory method & init()• “make”:

• x.makeIterator()

• x.makeWidget(cogCount: 47)

Factory method & init()• “make”:

• x.makeIterator()

• x.makeWidget(cogCount: 47)

Factory method & init()• “make”:

• x.makeIterator()

• x.makeWidget(cogCount: 47)

Factory method & init()• “make”:

• x.makeIterator()

• x.makeWidget(cogCount: 47)

Side-effects

Side-effects• Without: Noun

• x.distance(to: y) i.successor()

Side-effects• Without: Noun

• x.distance(to: y) i.successor()

• With: Verb

• x.sort()x.append(y)

Verb: Mutating / Nonmutating• “ed” or “ing”

“ed”

“ing”

Noun: mutating/ nonmutating• “form”

• Booleaneg: x.isEmpty, line1.intersects(line2)

• Booleaneg: x.isEmpty, line1.intersects(line2)

• Protocols what something is -> Noun eg: Collection

• Booleaneg: x.isEmpty, line1.intersects(line2)

• Protocols what something is -> Noun eg: Collection

• Protocols: capability -> -able, -ible, -ingeg: Equatable, ProgressReporting

• Booleaneg: x.isEmpty, line1.intersects(line2)

• Protocols what something is -> Noun eg: Collection

• Protocols: capability -> -able, -ible, -ingeg: Equatable, ProgressReporting

• types, properties, variables, and constants -> nouns.

Term of Art

Use Terminology Well

Use Terminology Well• Avoid obscure terms

Don’t say “epidermis” if “skin” will serve your purpose

Use Terminology Well• Avoid obscure terms

Don’t say “epidermis” if “skin” will serve your purpose

• Stick to the established meaning

Don’t surprise an expert

Don’t confuse a beginner

Use Terminology Well• Avoid obscure terms

Don’t say “epidermis” if “skin” will serve your purpose

• Stick to the established meaning

Don’t surprise an expert

Don’t confuse a beginner

• Avoid “non-standard” abbreviations

easily found by a web search.

Embrace precedent

• Array > List

• sin(x) > verticalPositionOnUnitCircleAtOriginOfEndOfRadiusWithAngle(x), sine(x)

• Precedent > Avoid abbreviation

Conventions• Document the complexity of computed property > O(1)

Conventions

Conventionsmethods and properties > free functions

Conventionsmethods and properties > free functions

1. No obvious self min(x, y, z)

Conventionsmethods and properties > free functions

1. No obvious self min(x, y, z)

2. function is unconstrained generic print(x)

Conventionsmethods and properties > free functions

1. No obvious self min(x, y, z)

2. function is unconstrained generic print(x)

3. function syntax is part of the domain notation sin(x)

Follow case conventions

Follow case conventions• Types and Protocols: UpperCamelCase

else: lowerCamelCase

Follow case conventions• Types and Protocols: UpperCamelCase

else: lowerCamelCase

• var utf8Bytes: [UTF8.CodeUnit] var isRepresentableAsASCII = truevar userSMTPServer: SecureSMTPServer

Follow case conventions• Types and Protocols: UpperCamelCase

else: lowerCamelCase

• var utf8Bytes: [UTF8.CodeUnit] var isRepresentableAsASCII = truevar userSMTPServer: SecureSMTPServer

• var radarDetector: RadarScanner var enjoysScubaDiving = true

Methods can share a base name• Methods can share a base name

Methods can share a base name• Methods can share a base name

Parameters

Defaulted Parameters

Defaulted Parameters

Defaulted Parameters

Defaulted Parameters

Defaulted Parameters

Defaulted Parameters

the end of the parameter list

Argument Labels

• Omit all labels when arguments can’t be usefully distinguished

• Value preserving type conversions

Argument Labels

• Omit all labels when arguments can’t be usefully distinguished

• Value preserving type conversions

Argument Labels

Argument Labels

Argument Labels(narrowing)

Argument Labels(narrowing)

Monomorphism• value preserving type conversion

Monomorphism

Int8 Int64

• value preserving type conversion

Monomorphism

Int8 Int64

• value preserving type conversion

Monomorphism

Int8 Int64

• value preserving type conversion

Monomorphism

Int8 Int64

• value preserving type conversion

Arguments Labels(prepositional phrase)

• eg: x.removeBoxes(havingLength: 12)

Arguments Labels(prepositional phrase)

• eg: x.removeBoxes(havingLength: 12)

Arguments Labels(prepositional phrase)

• eg: x.removeBoxes(havingLength: 12)

Arguments Labels(prepositional phrase)

• eg: x.removeBoxes(havingLength: 12)

• If the first argument forms part of a grammatical phrase, omit its label

• If the first argument forms part of a grammatical phrase, omit its label

• If the first argument forms part of a grammatical phrase, omit its label

• If the first argument forms part of a grammatical phrase, omit its label

• If the first argument forms part of a grammatical phrase, omit its label

• If the first argument forms part of a grammatical phrase, omit its label

• Label closure parameters and tuple members in your API.

• Label closure parameters and tuple members in your API.

• Label closure parameters and tuple members in your API.

• Label closure parameters and tuple members in your API.

Take extra care with unconstrained polymorphism

• eg: Any, AnyObject, unconstrained polymorphism

Take extra care with unconstrained polymorphism

• eg: Any, AnyObject, unconstrained polymorphism

Take extra care with unconstrained polymorphism

• eg: Any, AnyObject, unconstrained polymorphism

Take extra care with unconstrained polymorphism

• eg: Any, AnyObject, unconstrained polymorphism

To be continued… Function Naming In Swift 3