0Pricing
Swift Academy · Aula

Guia de estilo e diretrizes de design de APIs

Use nomes claros, rótulos de argumentos bem pensados, valores padrão sensatos e comentários de documentação concisos para projetar APIs Swift fáceis de usar.

Guia de estilo e diretrizes de design de APIs é uma aula grátis de Swift Academy no CoddyKit. Esta é a aula 2 de 3. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Swift Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Swift Academy inclui 3 aulas no total.

Princípios

Boas APIs são legíveis, previsíveis e pequenas.

  • Nomes que descrevem a intenção
  • Rótulos de argumentos úteis
  • Valores padrão para casos comuns
  • Documentação e exemplos concisos

Conceitos básicos de nomenclatura

Ações => verbos, dados => substantivos. Evite abreviações que ocultem o significado.

// 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

Rótulos de argumentos

Os rótulos ajudam os locais de chamada a soarem naturais: remove(at:), insert(_:at:).

// 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)

Bons valores padrão

Use parâmetros padrão para manter curtas as chamadas comuns, sem deixar de oferecer flexibilidade.

// 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)

Efeitos e mutabilidade

Torne os efeitos visíveis: use métodos mutating para alterações de estado e exponha visões somente leitura com private(set) quando apropriado.

// 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

Documentação de APIs

Dicas para comentários de documentação:

  • Comece com um resumo de uma única frase.
  • Declare o que a API faz, não como.
  • Mostre uma chamada de exemplo pequena.
  • Mencione pré-condições ou problemas de desempenho apenas se forem importantes.

Motivo para usar rótulos

Verificação rápida: Quando deve ser adicionado um rótulo externo?

Recapitulação

Recapitulação: Prefira nomes claros, adicione rótulos que proporcionem uma leitura natural, ofereça valores padrão para chamadas comuns, torne os efeitos explícitos e mantenha a documentação curta, com um exemplo.

Perguntas Frequentes

A aula “Guia de estilo e diretrizes de design de APIs” é grátis?

Sim — o texto completo de “Guia de estilo e diretrizes de design de APIs” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Swift Academy, atualize para CoddyKit PRO. O curso de Swift Academy inclui 3 aulas no total.

O que vou aprender em “Guia de estilo e diretrizes de design de APIs”?

Use nomes claros, rótulos de argumentos bem pensados, valores padrão sensatos e comentários de documentação concisos para projetar APIs Swift fáceis de usar. Você pratica Swift Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar Swift Academy?

Nenhuma experiência prévia é necessária. Swift Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 2 de 3.

Quanto tempo leva a aula “Guia de estilo e diretrizes de design de APIs”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de Swift Academy?

Sim. Cada aula de Swift Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

  1. Noções básicas de SwiftFormat / SwiftLint
  2. Guia de estilo e diretrizes de design de APIs
  3. Documentando código (introdução ao DocC)
← Voltar para Swift Academy