Desenhar a API pública
Sete decisões de assinatura — e a que decide se alguém consegue usar a sua biblioteca sem abrir o código.
A API é o que a pessoa lê. Tudo o mais — a implementação, os testes, a documentação — existe para sustentá-la, e nenhum deles a conserta depois de publicada.
O nome diz o que devolve#
| Nome | O que ele promete | Devolve |
|---|---|---|
buscar | procura, pode não achar | o valor ou void |
exigir | procura, e falha se não achar | o valor, sempre |
tem | uma pergunta | yes/no |
de | constrói a partir de | o objeto novo |
para | converte para | a outra forma |
com | uma cópia mudada | objeto novo |
definir | muda no lugar | nada útil |
Posicional até três; depois, opções#
dataforge
// Tres posicionais ainda se leem.
// Tabela.montar(linhas, colunas, titulo)
//
// Cinco nao:
// Tabela.montar(linhas, colunas, titulo, yes, no, 3, "—")
// ? ? ? ?
//
// A partir dai, o que varia vira um vault de opcoes.
action montar(linhas, colunas, opcoes := {}):
o := {"titulo": "", "totais": no, "largura": 0, "vazio": "—"}
cycle chave in opcoes.keys():
given chave not in o:
trigger $"'{chave}' nao e uma opcao de montar"
o[chave] := opcoes[chave]
yield $"{len(linhas)}x{len(colunas)}, vazio='{o['vazio']}'"
out montar([1, 2], ["a"], {"vazio": "-"})
assert montar([1], ["a"]) is "1x1, vazio='—'"Aceitar as três formas de “um campo”#
Uma função que recebe “o campo pelo qual ordenar” precisa funcionar com vault, record e instância. Este foi um bug real da própria biblioteca: sort_by_field devolvia void para todos os records, calada.
dataforge
adopt Arcane.Reflexo as R
action campo_de(item, nome):
given typeof(item) is "Vault":
yield item[nome] ?? void
yield R.ler(item, nome)
record Pessoa:
nome: String
idade: Integer
assert campo_de({"idade": 30}, "idade") is 30
assert campo_de(Pessoa("Ana", 41), "idade") is 41O que nunca entra numa assinatura pública#
| Não | Porque |
|---|---|
| um booleano sem nome | montar(l, c, yes, no) é ilegível na chamada; vire opção |
um índice mágico (-1 = todos) | o dia em que -1 for legítimo não tem saída |
| um tipo do Python vazando | list e dict não existem nesta linguagem |
| ordem de argumentos que muda | é a quebra mais barata de cometer e a mais cara de achar |
| um parâmetro que só faz sentido junto de outro | dois parâmetros com uma regra entre eles são um objeto |
Continue em O vault de opções e Os erros da sua biblioteca.