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.