Post on 09-Jan-2017
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