Documentação em Swift: como escrever código que fala por si só

Por que a documentação é um superpoder do desenvolvedor

Imagine: você abre um projeto alheio em Swift seis meses depois de ele ter sido escrito. O código funciona, mas entender por que o autor fez exatamente assim, e não de outra forma, é impossível. Não há comentários, nomes de variáveis no estilo a1, temp2. Familiar?

Uma boa documentação não é apenas uma cortesia para o seu eu futuro. É uma ferramenta que economiza horas de depuração, acelera a integração de novos desenvolvedores e transforma o caos em um sistema organizado. Neste artigo, vamos abordar as melhores práticas de documentação de código Swift, desde comentários básicos até o avançado DocC.

Fundamentos: de comentários simples a descrições significativas

//, /// e /* */ — quando usar cada um

Em Swift, existem três tipos de comentários, e cada um tem sua função:

• Comentários de linha única // — para anotações rápidas, TODO ou desativação temporária de código. Não abuse: se o comentário explica o óbvio, é desnecessário.
• Comentários de múltiplas linhas /* */ — para blocos de explicação ou desativação de trechos inteiros de código durante a depuração.
• Comentários de documentação /// — esta é sua principal ferramenta. O Xcode os captura automaticamente e os exibe no Quick Help.

/// Calcula a área do círculo a partir do raio./// - Parameter radius: Raio do círculo em metros./// - Returns: Área em metros quadrados./// - Throws: `InvalidInputError.negativeRadius`, se radius < 0.func areaOfCircle(radius: Double) throws -> Double {    guard radius >= 0 else {        throw InvalidInputError.negativeRadius    }    return Double.pi * radius * radius}

Comentário ruim vs comentário bom

Compare as duas abordagens:

// RUIM: Comentário óbvio// Incrementa o contador em 1counter += 1

// BOM: Explica o "porquê"// Usamos incremento porque esta é uma seção crítica// de desempenho, e a operação ++ está obsoleta em Swiftcounter += 1

A regra de ouro: o comentário deve responder à pergunta "por que", e não "o que" o código faz. O código em si deve ser legível para que o "o que" seja compreendido sem palavras.

DocC — documentação de nova geração

O que é DocC e por que é indispensável

Com o lançamento do Xcode 13, a Apple apresentou o DocC (Documentation Compiler) — uma ferramenta que transforma seus comentários /// em uma documentação bonita e interativa diretamente no Xcode e na web. Chega de arquivos PDF e páginas wiki que ficam desatualizadas em uma semana.

Como usar o DocC no projeto

1. Configuração: No Xcode, selecione Product → Build Documentation. O DocC compila automaticamente todos os símbolos documentados.
2. Links dentro da documentação: Use `` para links para outros tipos:

/// Use ``NetworkManager`` para enviar requisições./// Mais detalhes no artigo <doc:NetworkGuide>.

3. Recursos Markdown: O DocC suporta títulos, listas, tabelas, imagens e até diagramas Mermaid:

/// # Algoritmo de funcionamento/// 1. Verificação do cache/// 2. Se não houver — requisição ao servidor/// 3. Salvamento do resultado

Criando documentação para um módulo inteiro

Adicione o arquivo Documentation.docc na raiz do projeto. Dentro, uma estrutura em Markdown:

// MyFramework.docc/MyFramework.md# ``MyFramework``

Biblioteca assíncrona para trabalhar com rede.

## Topics

### Componentes principais- ``NetworkManager``- ``RequestBuilder``

### Extensões- <doc:CustomizingRequests>

Técnicas avançadas: escrevendo documentação que é lida

Estruture por funções

Nem todo código requer o mesmo nível de detalhamento. Divida a documenta