คู่มือรูปแบบและแนวทางการออกแบบ API

หลักการ

พื้นฐานการตั้งชื่อ

// Prefer clear, simple names.
// BAD:
func doCalc(_ a: Int, _ b: Int) -> Int { a + b }

// GOOD:
func sum(_ a: Int, _ b: Int) -> Int { a + b }

// BAD (ambiguous):
struct Cfg { let v: Int }
// GOOD (nouns for data types):
struct Configuration { let retries: Int }

print(sum(2, 3))  // 5

ป้ายกำกับอาร์กิวเมนต์

// Choose labels that explain a parameter's role.
// BAD:
func remove(_ index: Int) { print("remove", index) }

// BETTER:
func remove(at index: Int) { print("remove at", index) }

// Mixed labels:
func insert(_ item: String, at index: Int) {
    print("insert", item, "at", index)
}

remove(at: 2)
insert("a", at: 1)

ค่าเริ่มต้นที่ดี

// Provide defaults to cover the 80% case.
func greet(_ name: String, times: Int = 1, shout: Bool = false) {
    let msg = shout ? "HELLO, \\(name)!" : "Hello, \\(name)!"
    for _ in 0..<times { print(msg) }
}

greet("Ana")                 // default: once, not shouting
greet("Ben", times: 2)
greet("Cara", shout: true)

ผลกระทบและการเปลี่ยนแปลงค่า

// Prefer pure functions when possible; name mutating effects explicitly.
struct Counter {
    private(set) var value = 0
    mutating func increment(by amount: Int = 1) { value += amount }
}

var c = Counter()
c.increment()
c.increment(by: 3)
print("value =", c.value) // 4

การจัดทำเอกสาร API

เหตุผลในการใช้ป้ายกำกับ

สรุปทบทวน