Quais princípios básicos você gostaria em uma biblioteca?

Falam sobre qual sintaxe e recurso você gosta em uma linguagem de programação; agora perguntarei quais princípios ou recursos essenciais você gostaria em uma biblioteca em seu idioma favorito (ou qualquer outro)?

Um exemplo é adicionar a lista + = anotherList válida, em vez de permitir apenas a lista + = listElement (embora alguns possam ver isso como uma má ideia)

Eu seguiria as melhores práticas que você pode encontrar em Como criar uma boa API e por que isso é importante por Joshua Blosh (Google) . A versão em PDF pode ser encontrada aqui .

Segundo ele, as características de uma boa API são:

Fácil de aprender
Fácil de usar, mesmo sem documentação
Difícil de usar incorretamente
Fácil de ler e manter o código que o utiliza
Suficientemente poderoso para atender aos requisitos
Fácil de estender
Apropriado para o público

Eu quero o seguinte:

• Um espaço de nome claramente definido. Como C é meu idioma principal, também quero que as macros correspondam a isso. Resolver conflitos nessa área é péssimo.

• Se você alocar alguma coisa, me dê uma pista óbvia de que ela precisa ser liberada. Isso vai para o meu próximo ponto, que é a documentação.

• Documente a biblioteca. Ferramentas como o Doxygen são simples e portáteis, não há desculpa para não me dar algo que eu possa gerar e navegar.

• Documente tipos opacos em cabeçalhos públicos. Vou encontrá-los de qualquer maneira, me diga por que você não quer que eu mexa com eles e o que poderia acontecer se eu o fizesse. Se você realmente quer remendos, preciso saber o que você estava pensando.

• Não caia e corra. Eu realmente aprecio comentários como "Por favor, não entre em contato comigo sobre isso. Não tenho intenção de mantê-lo. Isso resolveu meu problema imediato, talvez ele resolva o seu problema. Eu não me importo, não vou atualizar isso e você pode ficar à vontade para bifurcar. " Eu não posso te dizer quanto tempo isso me salva.

• Não deve adicionar vazamentos de memória ou erros ao código existente. Se você não testou antes de enviar coisas para o seu próprio código, por que está me tentando?

• Se for realmente uma biblioteca, use uma licença permissiva e seja consistente. Não decida daqui a três meses que você deve ganhar mais dinheiro com isso. Isso é mais do que irritante na noite anterior ao envio de algo e você percebe que precisa reescrever um monte de código de biblioteca porque a licença foi alterada. Esse é exatamente o tipo de coisa que me deixa irritado o suficiente para reimplementar suas coisas sob a licença do MIT.

• Seja consistente no estilo de codificação, outras pessoas precisam ler seu código para descobrir o que ele está realmente fazendo quando as coisas não funcionam como o esperado.

• Não use mais de 110 colunas; seu código pode ter que ser editado no lugar e talvez eu tenha apenas uma tela de 80x25. Se você contar com guias para deixar as coisas mais "elegantes", terá outros problemas a resolver.

• Tente considerar pelo menos portas, se não estiver lidando com uma linguagem interpretada. Mesmo assim, tente considerar pelo menos as portas.

• Me dê testes. Espero que você os tenha, posso sugerir o contrário e, na verdade, posso ajudar a escrevê-los com base em um gráfico de chamadas. Se eu passar por todo esse problema, por favor, use-os . Caso contrário, você receberá patches que "funcionam para mim !!!" :)

• Não quebre a API, ponto final. Sei que você pode perceber que errou tudo, mas verifique se as coisas vinculadas a você não quebram em uma atualização simples. Isso pode significar algumas críticas e críticas, bem-vindo ao mundo das bibliotecas.

• Dê-me um roteiro para não duplicar seu trabalho ou o trabalho de outras pessoas.

Provavelmente vou editar esta postagem para adicionar mais.

Estou mais preocupado com os recursos flexíveis de uma API. Isso é:

• Simplicidade
• Consistência
• Elegância
• Intuitivo
• Simplesmente funciona

Eu poderia escrever um livro sobre como eles se aplicam ou seriam implementados, mas basta dizer que, a menos que um usuário da API possa entender como usá-la efetivamente, é de uso limitado. Simplicidade não significa simplismo, assim como elegância não significa onate. Simplesmente significa que é perfeito para o trabalho. Quanto menos alguém tiver que pensar em como usar a API, mais ela poderá usá-la.

A aparência delas depende do idioma, objetivo e público-alvo da API. O último critério se resume ao princípio da menor surpresa. Não há erros nos quais você não os esperava. Qualquer interpretação razoável da API obterá os resultados desejados.

Tornar possíveis coisas simples e complicadas

Isso resume muito bem qualquer outra filosofia de design. Se a sua biblioteca apenas possibilitar coisas complicadas, as pessoas que procuram resolver os 80% dos casos de uso mais fáceis serão tentadas a reinventar a roda, em vez de lidar com sua monstruosidade superengenharia que exige que você use 6 classes diferentes para fazer o equivalente à sua biblioteca "Olá Mundo".

Se sua biblioteca simplificar as coisas simples, as pessoas ficarão irritadas muito rapidamente quando descobrirem que precisam reescrever seu código apenas porque tinham um requisito que estava um pouco fora do caminho comum.

As melhores maneiras de conseguir isso são:

• Seja liberal no que você aceita. Se você estiver programando em uma linguagem dinâmica, use a digitação de pato para obter o máximo efeito. Se você estiver programando em C ++ ou D, use modelos sempre que possível. Aceite qualquer coisa que satisfaça alguma interface estrutural razoavelmente universal. Não force seus usuários a realizarem muito trabalho de conversão de dados de um formato para outro.

• Crie funcionalidade de alto nível em sua biblioteca, mas de forma transparente sobre a funcionalidade de nível inferior e verifique se a funcionalidade de nível inferior existe para as pessoas que precisam.

• Siga o princípio da menor surpresa por padrão, mesmo que isso possa limitar a flexibilidade ou a eficiência. Se necessário, adicione uma segunda função com um nome mais detalhado que enfatize sua surpresa para permitir otimizações ou maior flexibilidade.

• O encapsulamento é útil, mas não se preocupe. Pessoas com requisitos incomuns e imprevistos ocasionalmente podem precisar entrar em uma de suas abstrações para concluir o trabalho. Por outro lado, deve ser difícil dar um tiro no próprio pé por acidente, ao usar construções aparentemente inocentes . Lembre-se disso ao decidir com que força deseja bloquear as coisas.

• Use exemplos intensamente em sua documentação. Isso serve tanto para ilustrar casos de uso comuns para o usuário quanto para forçá-lo a pensar se os casos mais comuns são suficientemente simplificados.

• Tenha padrões razoáveis ​​para tudo o que puder, mas verifique se esses padrões são apenas padrões e que está claro como substituí-los.

• Minimalismo razoável e saudável

Isso é tudo. Compare, como exemplo, o mecanismo de pipes no Windows e no UNIX. Um deles oferece um monte de funções especializadas da API com vários argumentos obscuros, desnecessários ou raramente usados, cada um dos quais pode ter um dos muitos valores de macro / constante. O UNIX basicamente reutiliza a interface de abrir / ler / gravar / fechar existente, além de alguns métodos muito simples para alguns casos específicos, como socketpair () ou pipe (). Há realmente quase, quase nada de novo que você deve aprender para usar pipes no UNIX. Agora compare com isso .

(Para ser justo, a Microsoft originalmente "apenas emprestou" essa interface do OS / 2 da IBM.)