Enviando minha biblioteca de primeira classe. Alguma dica que eu preciso estar ciente?


12

Sou desenvolvedor da Web prestes a desbloquear a conquista "Publicação da biblioteca de primeira classe" em minha carreira e estou suando a bala (fiquei acordado a noite toda estressado). Gostaria muito de aproveitar a experiência da comunidade para ver se alguém tem alguma sugestão ou recomendação para garantir que tudo corra o mais suavemente possível. Há algum detalhe ou dicas que eu preciso conhecer? Alguma coisa especial sobre o processo de compilação que possa voltar para me morder?

Aqui é onde estou:

  • A biblioteca é testada em unidade e possui aproximadamente 97% de cobertura de código
  • A API está bem documentada e foram criados documentos XML para suporte ao intellisense
  • Garanti que os acessadores de classe pública / privada sejam precisos e corretos. O mesmo vale para todos os getters / setters
  • A manipulação de erros não é tão graciosa quanto eu gostaria que fosse, mas sou contra um prazo e aceitei que é "tão bom quanto vai ser" por enquanto
  • Nenhum registro amigável. O Debug.Writeline foi usado extensivamente ... Aprendi recentemente que isso é um reflexo da minha inexperiência :(

Seu conselho é muito apreciado!

A biblioteca será usada para gerar relatórios. Chapéu padrão - conecta-se ao banco de dados somente leitura, executa cálculos, formata e gera dados para o fluxo de resposta.


Fui apontado como um recurso adicional para preencher um dos programadores que desistiram, e essa tarefa foi dada a mim como um projeto de "cortar os dentes". A biblioteca de classes será lançada para outros programadores da empresa usarem enquanto escrevem o código de produção.


2
Precisa de detalhes, libere como? Liberar para venda? Liberar código-fonte aberto para compartilhamento? Liberar para um cliente por contrato em que você está? Liberando para o resto da sua organização de desenvolvimento como parte de um projeto para seu empregador em período integral? Liberando como v1.0 de um novo produto a disponibilidade do cliente para seu empregador em período integral?
Jimmy Hoffa

@ JimmyHoffa: respostas adicionadas às suas perguntas. Obrigado por dedicar um tempo!
JavaScript Sr.

1
Finja que você é um usuário da biblioteca sem conhecimento de como ela funciona. Use-o para construir algo. Altere / remova / adicione itens com base na experiência. Em seguida, libere-o para usuários reais e obtenha seu feedback.
mike30

Talvez use o Sandcastle ou outra biblioteca geradora de documentos para ter material de referência offline (ish)?
Jesse C. Slicer

7
relaxar. Ter até um único teste de unidade e uma única linha de documentação da API já eleva essa versão acima de ~ 95% do código "liberado para uso de outros programadores na empresa", na minha experiência.
precisa saber é o seguinte

Respostas:


8

Bloquear a API

A arte de criar efetivamente uma API é tanto sobre o gerenciamento de expectativas quanto sobre a estrutura.

Quando digo API, estou me referindo especificamente a como os métodos / classes públicos / internos são nomeados e qual é seu nível de acesso (por exemplo, privado / público / interno).

Se você está preocupado com o fato de o código não estar completamente pronto no horário nobre, você sempre pode publicá-lo inicialmente como beta.

Lançamentos:

  • Beta (ou seja, pré-1,0)

    • pode conter várias alterações de quebra de API
    • pode não ter alterações de compatibilidade com versões anteriores entre versões
    • pode ter falta de polimento
  • Oficial (1.0+)

    • A API está bloqueada até a próxima versão principal
    • quaisquer alterações introduzidas devem garantir compatibilidade com versões anteriores
  • Menor (ex 1.1)

    • contêm correções de erros e implementações de recursos
    • pode adicionar, mas não tirar, a API definida

Se você acha que a API precisa ser reforçada, libere-a por um tempo como beta. Isso indica que está disponível para uso, mas não deve ser usado para produção e / ou código de missão crítica.

Muitas pessoas tratam esquemas de controle de versão numerados, como o hogwash, mas quando usados ​​de maneira eficaz, podem ser usados ​​para fornecer espaço de manobra até que a estrutura seja resolvida.

Suas suposições sobre como serão usadas estão erradas

Não importa o quão bem algo seja projetado, as pessoas encontrarão uma maneira de abusar ou criar um uso alternativo.

Uma maneira de lidar com isso é bloquear o máximo possível da implementação usando os acessadores (por exemplo, privado / público / interno), mas nenhuma quantidade de design ou engenharia fornecerá o insight necessário para liberar o código aos usuários.

Realmente não importa o quão 'perfeito' você acha que seu código pode se tornar, seus usuários provarão que não é.

Eu argumentaria que essa é a principal razão pela qual é sempre melhor usar uma base de código existente em vez de fazer uma reescrita completa. Na melhor das hipóteses, uma reescrita completa reduzirá o inchaço, mas há uma alta probabilidade de que a nova base de código contenha tantos (e possivelmente mais) bugs quanto a base de código original.

No seu caso, você está fortalecendo a batalha do zero, para poder começar.


Parece que você tem o resto de suas bases cobertas. A documentação da API é vital e os testes serão bons para garantir a estabilidade quando forem feitas alterações no futuro.

A implementação de um esquema de log consistente será importante antes que o código seja lançado para produção, pois você precisará de uma maneira de ativar / desativar / filtrar globalmente os logs. BTW, na maioria dos casos, o log envolve realmente importar uma biblioteca e alterar as chamadas de saída de Debug.WriteLine () para algo como Logging.Debug (), Logging.Info (), Logging.Error (). O próprio criador de logs fornece apenas uma implementação padrão para configuração, filtragem e uma ampla variedade de esquemas de saída (ex arquivos, console, etc.).

Fora isso, eu procuraria obter o código e ser usado. Mesmo que apenas por um pequeno número de usuários para começar.


1
+1 Re: log - eu recomendo o TraceSource . Ele não apresenta dependências externas, pois faz parte das principais bibliotecas .NET e permite que os usuários anexem ouvintes e configurem o rastreamento por meio de arquivos de código e app.config.
Dan Lyons

4

Essas são duas coisas que considero essenciais para o lançamento de software:

  • Saiba exatamente o que você lançou
  • Gerenciar expectativas

Você deseja voltar e corrigir o que lançou e deseja que as pessoas entendam o problema que seu código resolverá.

Saber o que você lançou

Verifique se a versão e a assinatura estão corretas (se for o caso). Use seu controle de origem para marcar \ rotular o código associado à versão lançada oficialmente. Isso o ajudará a identificar os bugs com mais facilidade, pois você pode voltar exatamente ao código fonte que lançou. Também ajudará na linha quando você tiver algumas versões diferentes lançadas.

Tente facilitar a atualização e a versão mais recente. Seja um instalador ou simplesmente colocando-o em um compartilhamento comum, depende de quem \ quando \ com que frequência você enviará.

Certifique-se de que alguém revise sua versão final, incluindo a documentação. É muito fácil ficar nervoso ou animado com o lançamento de software e perder alguma coisa.

Gerenciando expectativas

Documente as limitações e torne-as razoavelmente óbvias para os desenvolvedores. É bom que você os tenha encontrado. As pessoas geralmente entendem mais se conhecem as limitações do seu software, especialmente se você tem um plano para corrigi-las.

Documente como você gostaria de receber feedback, bom ou ruim. Como é um projeto interno, se todos tiverem acesso a um sistema comum de rastreamento de erros, peça que eles arquivem erros no projeto apropriado.

No futuro, evite alterar a API, se possível, essa é a única coisa com potencial para incomodar seus clientes. Lembre-se de que as exceções também fazem parte da API, embora em C # elas não façam parte da documentação do método. Ele pode ser possível melhorar as exceções que estão sendo jogados em uma data posterior, mas você vai precisar de falar com os usuários finais e ver o impacto que isso terá.


0

Eu tenho uma lista de verificação para implantações que você pode achar útil. Eu desenvolvo o desktop, mas isso deve ser traduzido. Aqui estão algumas delas:

Geral:

  • Coloque verificações nulas para parâmetros de função que não devem ser nulos. Isso me ajuda a falhar cedo.
  • Remova comentários desnecessários e arquivos com comentários. Isso causa trabalho futuro.
  • Pesquise qualquer comentário "// TODO". Às vezes deixo anotações para mim. Às vezes eu esqueço deles.
  • Execute um teste do meu código usando o banco de dados de produção sempre que possível. Isso ajuda a garantir que eu tenha todas as alterações no meu banco de dados no servidor de produção.
  • Coloque em log copioso. Especialmente para uma implantação inicial. Na verdade, salvei o log para o final, porque meu código geralmente está em gel neste momento. Você não quer estar em uma situação em que está travado e diz a si mesmo "Se ao menos eu soubesse qual era o valor de X no momento". Tente planejar com antecedência.
  • Tente agrupar chamadas de bibliotecas de terceiros em Fachadas. Isso facilita a troca de bibliotecas no futuro, além de fornecer uma lista de verificação do que você precisa de uma biblioteca.

.Net específico:

  • Verifique se estou chamando Dispose () em objetos descartáveis. Eu uso o Code Analysis ou o FxCop para ajudar a encontrar casos disso.
  • Verifique se estou desengatando todos os manipuladores de eventos corretamente. Isso evita vazamentos de memória.
Ao utilizar nosso site, você reconhece que leu e compreendeu nossa Política de Cookies e nossa Política de Privacidade.
Licensed under cc by-sa 3.0 with attribution required.