swift 3 を書くときに知っておきたい api デザインガイドライン...

84

Upload: tomohiro-kumagai

Post on 08-Jan-2017

3.907 views

Category:

Software


2 download

TRANSCRIPT

Page 1: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 2: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 3: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 4: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 5: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

話してきました

Page 6: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 7: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 8: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 9: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 10: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 11: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 12: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 13: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 14: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 15: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 16: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 17: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 18: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 19: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

pointer.assignFrom(source, count: 100)

pointer.assign(from: source, count: 100)

Page 20: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 21: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

// album, insert photo at current page. album.insert(photo, at: currentPage)

// album's photos remove all keeping capacity. album.photos.removeAll(keepingCapacity: true)

// album, insert photo page current page. album.insert(photo, page: currentPage)

// album's photos remove all capacity. album.photos.removeAll(capacity: true)

Page 22: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

// 要素の配列 から位置 x に該当するものを消す。 associatedtype ContentView : UIView func suffix(from start: Index) -> SubSequence

// 完全に役目を汲み取れなくなる例 associatedtype ViewType : UIView

// 型寄りの index よりは、役割寄りの start が明瞭な例 func suffix(from index: Index) -> SubSequence

Page 23: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

// 要素の配列 から、要素 x を消す。 elements.remove(x)

// 要素型の x であれば“要素である”ことは自明 elements.removeElement(x)

// デバイスの配列 で“element”という言葉は不適切 devices.removeElement(device)

// デバイスの配列 から、デバイスを消す。 devices.remove(device)

Page 24: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

// 要素の配列 から位置 x に該当するものを消す。 elements.remove(at: index)

// 要素の配列 から、要素 y を消す。 elements.remove(y)

Page 25: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

// 記録から、位置 x に該当する値を取得。 records.value(at: x)

// 記録から、列 y 行 z に該当する値を取得。 records.valueAt(row: y, column: z)

// 複数で構成時、ラベルに入れるとバランスが悪い。 records.value(atRow: y, column: z)

Page 26: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

// 指定したキーに対する値を更新する。 func updateValue(_ value: Any, forKey key: String)

// 名前で補足しないと、使用時に意味が汲み取れない。 updateValue(100, forKey: "A") update(100, for: "A")

Page 27: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

// 主目的はメッセージの表示。第2引数以降は副次的。

func print(_ items: Any..., separator: String, terminator: String, to output: inout Target)

Page 28: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

// 電子計算機の分野で、正弦関数 sin は適切な共通認識。 let answer = sin(1.5)

// 言葉を適切に把握してないと、何が起こるか判らない。 rinoa.junctioned(to: Bahamut.self).megaFlare()

Page 29: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 30: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 31: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 32: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

/// Inserts a new element /// into the collection at the specified index.

func insert(_ newElement: _Element, at i: Index)

Page 33: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 34: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

/// Advances to the next element and returns it, /// or `nil` if no next element

mutating func next() -> Element?

/// Returns a new string by concatenating the /// elements of the sequence, adding the given /// separator between each element.

func joined(separator: String = default) -> String

Page 35: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

/// Accesses the code unit at the given position.

subscript(position: Index) -> CodeUnit { get }

Page 36: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

/// Creates a view of the given string.

init(_ text: String)

Page 37: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

/// A raw pointer for accessing untyped data. struct UnsafeMutableRawPointer { … }

/// A textual representation of the range. var description: String { get }

/// Access the `Pointee` instance referenced by `self`. var pointee: Pointee { get }

Page 38: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

/// Creates a new value, rounded to the closest /// possible representatation. /// /// If two representable values are equally close, /// the result is the value with more trailing /// zeros in its significand bit pattern. /// /// - Parameter value: The integer to convert /// to a floating-point value. init(_ v: Int8)

Page 39: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

/// Returns the number of elements. /// /// - Complexity: O(1) if `Self` conforms /// to `RandomAccessCollection`; O(N) otherwise.

var count: IndexDistance { get }

Page 40: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 41: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

/// Creates a new value, rounded to the closest /// possible representatation. /// /// If two representable values are equally close, /// the result is the value with more trailing /// zeros in its significand bit pattern. /// /// - Parameter value: The integer to convert /// to a floating-point value. init(_ v: Int8)

Page 42: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

let f = Double.init(_:) as (Int8) -> Double

Page 44: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 45: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 46: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 47: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

// 型は名詞で名前をつける。 struct ObjectIdentifier { … }

// 変数名は名詞でつける。 let identifier = ObjectIdentifier(object)

// 真偽値プロパティーは主張重視。配列が空であるか。 items.isEmpty

Page 48: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

// 名詞系で、自身に影響しない場合は、名詞そのまま。 let answer = value.squareRoot()

// 名詞系で、自身に影響する場合は“form”接頭辞。 value.formSquareRoot()

// 動詞系で、自身に影響ないなら“-ed”か“-ing”接尾辞。 let answer = value.divided(by: 3)

// 動詞系で、自身に影響するなら、動詞そのまま。 value.divide(by: 3)

Page 49: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

// 範囲が、ある範囲と、重なる点があるか if range1.overlaps(range2) { … }

// 配列が、要素を、含んでいるか if items.contains(item) { … }

// 要素を返してるのか、要素を含むか判定してるのか。 let answer = items.contained(item) { … }

Page 50: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

// 内容を列挙するイテレーターを作る。 func makeIterator() -> Iterator

// ボタンを作る。表題を受け取る。 func makeButton(caption: String) -> NSButton

// ラベル名の英文的な流れは気にしない func makeButton(havingCaption: String) -> NSButton

Page 51: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

// 同じ値を表現する場合は、素直な型変換を表現する。 let value = Int32(value64)

// 再解釈を伴うなら、何が起こるかラベルで示唆する。 let value : Int32(truncatingBitPattern: value64)

Page 52: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

// 列挙子の名前は小文字で始める。 enum UnicodeDecodingResult { case scalarValue(UnicodeScalar) case emptyInput case error }

Page 53: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

// 具体的に“コレクション”を表現するので、名詞。 protocol Collection { … }

// 比較可能性を表現するので、接尾辞“-able”な名前。 protocol Comparable { … }

Page 54: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

// プロトコル名が役割と一致するなら、名称に Type を付与 associatedtype IteratorType : Iterator

// ただし、標準ではプロトコル名に Protocol が主流 associatedtype Iterator : IteratorProtocol

Page 55: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 56: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 57: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 58: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

// 同じ所属で、違う意味で基本名を共有している。 class Database { func index() // 索引の再構築 func index(of row: Row) -> Int // 行番号の取得 }

// 所属外とは干渉しない。所属内では同じ意味。 struct Bookshelf { func index(_ i: Int, offsetBy n: Int) -> Int { … } func index(after i: Int) -> Int { … } }

Page 59: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

// これらの機能は、関連している? struct String { init(_ value: Int) { … } init(_ value: Int, radix Int) { … } }

// 既定値を使えば、関連性を気にする必要さえない。 struct String { init(_ value: Int, radix Int = 10) { … } }

Page 60: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

// 指定したキーに対する値を更新する。 struct Variant { func value() -> Int func value() -> Double }

Page 61: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

// 配列の並び替えた値、と表現できる。 struct Array<Element> { func sorted() -> Array<Element> { … } }

// 所属が定まらない場合に、大域関数として扱う。 func max(_ x: Int, _ y: Int, _ z: Int)

// 数値の絶対値、所属はあっても abs(x) が慣習的。 func abs(_ x: Int) -> Int

Page 62: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

// もはや x, y, z は、どうでもいい。 let answer = max(x: 3, y: 5, z: 2)

// 慣習的に abs(x) な書き方が自然。 let answer = abs(value: -30)

Page 63: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

// Element = Any で束縛すると… struct Array<Element> { // element に [Any] が渡せる。 mutating func append(_ element: Element) { … } // elements に [Any] が渡せる。 mutating func append<S:Sequence>(_ elements: S) where S.Iterator.Element == Element { … } }

Page 64: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 65: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 66: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

#if swift(>=3.0)

// Swift 3.0 以上でコンパイルするコード

#else

// Swift 3.0 未満でコンパイルするコード

#endif

Page 67: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

// 新しい名前に変更する。 mutating func formUnion() { … }

// 旧名称を定義、名前の変更を明記する。 @available(*, unavailable, renamed: "formUnion") mutating func unionInPlace() { /* 実装不要 */ }

Page 68: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

// 新しい名前に変更する。 func advanced(by amount: Int) -> Int { … }

// 旧名称を定義、名前の変更を明記する。 @available(*, unavailable, renamed: "advanced(by:)") func advancedBy(_ amount: Int) -> Never { /* 実装不要 */ }

Page 69: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

// 新しい名前に変更する。 protocol Bookshelf { … }

// 旧名称を型エイリアスで定義し、新しい型を設定する。 @available(*, unavailable, renamed: "Bookshelf") typealias BookshelfType = Bookshelf

Page 70: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

// 列挙子を、新しい名前に変更する。 enum DecodingResult { case scalarValue(UnicodeScalar) case emptyInput case error }

// 列挙子は、自動で Fix-it の対象になる。

Page 71: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 72: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

// これを sorted に変えたい。 func sort() { … }

// これを sort に変えたいが、旧 sort と衝突する。 mutating func sortInPlace() -> Cards { … }

Page 73: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 74: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

// 旧実装はそのまま、新しい名称を指定する。

@swift3_migration(renamed="sorted()") func sort() -> Cards { … }

@swift3_migration(renamed="sort()") mutating func sortInPlace() { … }

Page 75: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 76: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 77: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 78: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift

// 何もしなくても、マイグレーションの対象になる。

enum DecodingResult { case ScalarValue(UnicodeScalar) case EmptyInput case Error }

func decode(source: String?) -> DecodingResult {

… }

Page 79: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 80: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 81: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 82: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 83: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift
Page 84: Swift 3 を書くときに知っておきたい API デザインガイドライン #love_swift #akibaswift