Buscando aconselhamento sobre documentação do sistema

5

Eu tenho um motor de classificação (é basicamente um algoritmo) que quando eu comecei não tinha documentação formal. Criamos uma especificação / decomposição funcional que é o nosso documento de nível comercial, mas agora eu preciso de algo mais técnico (uma especificação técnica).

O que eu estou tentando entender é como esse documento se parece, em que formato ele deve estar e em que nível de detalhes devemos entrar.

Estamos no processo de comentar todo o código. Também temos um documento bruto chamado Blueprint, que reflete o fluxo do modelo e é escrito em pseudocódigo. A combinação deste modelo e os comentários do modelo são suficientes como uma Especificação Técnica?

    
por Shadders 30.10.2012 / 12:46
fonte

2 respostas

1

O objetivo desse tipo de especificação é ajudar os funcionários que entram no código. Também deve ajudar os trabalhadores experimentados a ter uma visão geral clara do projeto.

Você pode alterar seu blueprint para um diagrama UML, especialmente um diagrama de atividades no seu caso. Isso oferece uma maneira (mais ou menos) padronizada de representar visualmente seu fluxo de trabalho. Ele mostra as ações realizadas no algoritmo, as escolhas feitas, as opções disponíveis para cada escolha, os loops, etc. Você também pode mostrar o início e o fim do processo, exibir os elementos necessários ou produzidos por ele e destacar alguns pontos graças aos comentários.

Em um nível inferior, comentar com inteligência o código é sempre uma boa ideia. Geralmente, deve-se especificar, para cada pedaço de código (função, método, classe, ...)

  • Suas entradas e quais propriedades devem respeitar (a lista deve ser classificada, etc.);
  • Sua saída;
  • O que acontece em casos específicos (uma lista vazia, uma entrada inválida etc.). Indique as exceções suscetíveis, se seu idioma as apoiar;
  • Seus efeitos colaterais (idealmente, não deve ter nenhum). Normalmente, os arquivos de leitura / gravação de / para, rede, etc .;
  • Se for thread safe. Ou seja, se seu estado puder ser alterado durante sua execução por uma entidade externa. Verifique, por exemplo, se a lista fornecida como entrada pode ser alterada externamente. Segurança de thread é muito importante em um ambiente multi-threaded, é claro, mas isso também é um sinal de qualidade. Os desenvolvedores devem ter muito cuidado ao usar um código inseguro.
  • Seu tempo e consumo de memória, sem suas entradas. Os usuários externos querem respostas para perguntas como "Posso dar uma lista (muito) grande para essa função sem nenhum problema importante de tempo de computação?".
  • O contexto no qual ele deve ser usado, se esse contexto puder afetar seu comportamento (idealmente, não deve ser o caso, já que os únicos fatores que influenciam devem ser suas entradas).
  • Se necessário, como criar e testar automaticamente.

Use ferramentas que permitem adicionar esses comentários ao seu código e gerar relatórios automaticamente em um documento separado. Veja javadoc ou doxygen , por exemplo. Graças a essas ferramentas, você pode atualizar as informações no mesmo momento em que altera seu código e obter uma documentação separada sempre atualizada.

Complete as especificações por testes automatizados e considere-os como parte da documentação. Os testes descrevem qual deve ser o comportamento do código em situações normais e situações excepcionais.

Seu mecanismo deve então ser considerado como uma coleção de entidades se comunicando juntas. Você sabe como cada entidade funciona, como as entidades devem agir juntas e como elas agem em situações representativas.

Note que isso não é uma defesa de OOP, já que as "entidades" podem ser funções (em programação funcional), estruturas, classes (em OOP), etc.

    
por 30.10.2012 / 14:51
fonte
0

Não escreva comentários apenas por causa disso. Comente a API pública, comente a expressão REGEX, comente algo realmente difícil (é raro encontrar todos os frameworks e ferramentas disponíveis). Eu não acho que isso seja uma solução para o seu problema.

Escreva um documento para uma pessoa que não sabe nada sobre o que você está fazendo. O documento deve explicar por que você está fazendo isso, como você está fazendo isso e como ele pode ser testado (validado).

Encontre alguém que não saiba nada sobre o que você está trabalhando. Dê-lhes o documento. Se faz todo o sentido para eles, então você fez um bom trabalho, caso contrário, volte para a prancheta.

    
por 31.10.2012 / 01:01
fonte