Documentando a lógica matemática no código

Às vezes, embora não frequentemente, tenho que incluir lógica matemática no meu código. Os conceitos usados ​​são geralmente muito simples, mas o código resultante não é - muitas variáveis ​​com objetivos pouco claros e algumas operações com intenções não tão óbvias. Não quero dizer que o código seja ilegível ou impossível de manter, apenas que é muitíssimo mais difícil de entender do que o problema real de matemática. Tento comentar as partes mais difíceis de entender, mas há o mesmo problema em apenas codificá-las - o texto não tem o poder expressivo da matemática .

Estou procurando uma maneira mais eficiente e fácil de entender de explicar a lógica por trás de parte do código complexo, de preferência no próprio código. Eu considerei o TeX - escrever a documentação e gerá-la separadamente do código. Mas então eu teria que aprender TeX, e a documentação não estará no próprio código. Outra coisa em que pensei foi tirar uma foto das notações matemáticas, equações e diagramas escritos em papel / quadro branco e incluí-los no javadoc.

Existe uma maneira mais simples e clara?

PS A atribuição de nomes descritivos (em timeOfFirstEventvez de t1) às variáveis ​​torna o código mais detalhado e ainda mais difícil de ler.

A coisa certa a se fazer nessas circunstâncias é implementar o algoritmo, a fórmula ou o que quer que seja exatamente com os mesmos nomes de variáveis ​​da fonte primária do mundo real (na medida em que a linguagem de programação permitir isso) e ter um comentário sucinto acima dizendo algo como "computação à distância de Levenshtein, como descrito em [Knuth1968]", onde a citação se vincula a uma descrição facilmente acessível da matemática.

(Se você não tem essa referência, mas sua matemática é sólida e útil, talvez você deva publicá-la. Basta dizer.)

Quando tive que implementar algoritmos assim, existem algumas coisas que faço.

1. Tanto quanto possível, isole o algoritmo para seu próprio método ou de preferência classe. Meu projeto atual tem sua própria Mathclasse equivalente à qual adicionar algoritmos complexos.

2. Forneça um resumo do que o algoritmo deve fazer em termos leigos, incluindo acrônimos comuns ou referências abreviadas ao termo. Eu faço isso no próprio método, para que ele viva com o código.

3. Forneça um resumo do algoritmo em termos técnicos / matemáticos e inclua quaisquer referências externas que eu conheça. Mais uma vez, faço isso com o próprio método, para que tenha uma melhor chance de permanecer relevante. O texto sem formatação não é ótimo nesse caso, portanto, citarei o termo matemático da melhor maneira possível e esclarecerei em um comentário entre parênteses. Por exemplo, x^y (x raised to the power y)

4. Documente como estou dividindo o algoritmo em componentes e indique o que cada variável representa no algoritmo. por exemplo.t1 is time of first event

5. Codifique o algoritmo e comente as partes complexas. Basicamente, adicionarei um comentário em qualquer lugar que eu dê um passo que não fosse óbvio ou direto no próprio algoritmo. Eu especialmente garanto que comente quaisquer atalhos não óbvios e por que eles estão bem que eu possa usar na implementação.

6. Escreva alguns testes de unidade que validarão a operação do algoritmo.

Finalmente, se é realmente, muito, muito complexo, então me resigno ao fato de possuir esse código pelo restante do meu tempo nesse projeto.

Não gosto de confiar em um documento externo para que outra pessoa entenda o código. Sim, às vezes pode ser necessário, especialmente quando entrar em detalhes misteriosos. Mas sempre que possível, tento manter tudo dentro do próprio código, para que ele tenha a chance de permanecer atualizado e facilmente localizado. Nesse caso, eu valorizo ​​a acessibilidade às informações sobre a expressividade da documentação.

Em nossos projetos, que estão girando em torno de pesquisas em economia financeira quantitativa, utilizamos MUITA matemática e seguimos uma combinação do que já foi publicado:

1. Forneça um link para a fonte principal que você está usando. Para nós, a maneira mais fácil de fazer isso é usar o identificador BibTex, que é basicamente um ID para um artigo que pode ser consultado por todos os envolvidos. Dependendo da fonte específica, também adicionamos regularmente a referência da equação.

2. Forneça explicações para todas as variáveis. Novamente, usamos Tex para isso, se o artigo original usa letras gregas ou outras. A razão para isso é que, com freqüência, papéis e livros usam notações diferentes. Se alguém precisar refazer a matemática, isso será muito mais fácil.

3. Tente codificar a equação em uma peça. É muito mais fácil reconhecer dessa maneira. NÃO publique o código Tex da equação completa no código - a equação é muito curta e a postagem de tex é confusa e supérflua, ou a equação é enorme e o código tex é inútil, a menos que você o compile (use um referência). Desmontar uma equação em pedaços pequenos torna muito difícil entender o que está acontecendo (se você é bom em matemática, pelo menos).

IMHO, a percepção mais importante é que as fórmulas geralmente dependem do contexto. Todo trabalho de matemática que conheço leva tempo para configurar o ambiente do modelo; Você deveria fazer o mesmo.

o texto não tem o poder expressivo da matemática

Você está certo. Como você já está procurando uma maneira de fazê-lo fora do código, e Tex é um exagero além de ter uma curva de aprendizado acentuada, minha recomendação é a seguinte:

Use o OpenOffice.org/LibreOffice Math Equation Editor.

É grátis. Está aberto.

Você pode usá-lo visualmente ou escrever as equações em um idioma especial.

Você não precisa aprender o idioma imediatamente, porque quando você usa a GUI, o "código" é gerado em um painel para você ver.

No painel superior, você pode "desenhar" as equações usando uma paleta. No painel inferior, a notação equivalente é gerada. Você pode fazer o contrário, depois de entender a notação, escrevendo em notação no painel inferior e vendo a saída gráfica no painel superior.