Documenter la logique mathématique dans le code

Parfois, mais pas souvent, je dois inclure la logique mathématique dans mon code. Les concepts utilisés sont pour la plupart très simples, mais le code qui en résulte ne l'est pas - beaucoup de variables avec un but peu clair, et certaines opérations avec une intention pas si évidente. Je ne veux pas dire que le code est illisible ou ingérable, juste qu'il est waaaay plus difficile à comprendre que le problème de mathématiques réel. J'essaie de commenter les parties les plus difficiles à comprendre, mais il y a le même problème que pour les coder - le texte n'a pas le pouvoir expressif des mathématiques .

Je recherche une manière plus efficace et plus facile à comprendre d'expliquer la logique derrière certains codes complexes, de préférence dans le code lui-même. J'ai envisagé TeX - écrire la documentation et la générer séparément du code. Mais alors je devrais apprendre TeX, et la documentation ne sera pas dans le code lui-même. Une autre chose à laquelle j'ai pensé est de prendre une photo des notations mathématiques, des équations et des diagrammes écrits sur papier / tableau blanc, et de l'inclure dans javadoc.

Existe-t-il un moyen plus simple et plus clair?

PS Donner des noms descriptifs ( timeOfFirstEventau lieu de t1) aux variables rend le code plus verbeux et encore plus difficile à lire.

La bonne chose à faire dans de telles circonstances est d'implémenter l'algorithme, la formule ou quoi que ce soit avec exactement les mêmes noms de variables que dans la source principale du monde réel (dans la mesure où le langage de programmation le permet), et d'avoir un commentaire succinct dessus: quelque chose comme "Calcul de distance de Levenshtein comme décrit dans [Knuth1968]", où la citation renvoie à une description facilement accessible des mathématiques.

(Si vous ne disposez pas d' une telle référence, mais que vos calculs sont solides et utiles, vous devriez peut-être envisager de les publier vous-même. Dites-le simplement.)

Quand j'ai dû implémenter des algorithmes comme ça, il y a quelques choses que je fais.

1. Autant que possible, isolez l'algorithme selon sa propre méthode ou de préférence sa classe. Mon projet actuel a sa propre Mathclasse équivalente à laquelle ajouter des algorithmes complexes.

2. Fournissez un résumé de ce que l'algorithme est censé faire en termes simples, y compris tout acronyme commun ou référence abrégée au terme. Je le fais dans la méthode elle-même, donc elle vit avec le code.

3. Fournir un résumé de l'algorithme en termes techniques / mathématiques et inclure toutes les références externes que je connais. Encore une fois, je le fais avec la méthode elle-même afin qu'elle ait de meilleures chances de rester pertinente. Le texte brut n'est pas génial dans ce cas, je vais donc citer le terme mathématique du mieux que je peux et clarifier dans un commentaire entre parenthèses à côté. Par exemple, x^y (x raised to the power y)

4. Documentez comment je divise l'algorithme en composants et indiquez ce que chaque variable représente dans l'algorithme. par exemple.t1 is time of first event

5. Codez l'algorithme et commentez les parties complexes. Essentiellement, j'ajouterai un commentaire partout où je franchirai une étape qui n'était pas évidente ou simple dans l'algorithme lui-même. Je m'assure en particulier de commenter tous les raccourcis non évidents et pourquoi ils sont corrects que je puisse prendre dans la mise en œuvre.

6. Écrivez quelques tests unitaires qui valideront le fonctionnement de l'algorithme.

Enfin, si c'est vraiment, vraiment, vraiment complexe, je me résigne au fait que je possède ce code pour le reste de mon temps sur ce projet.

Je n'aime pas me fier à un document externe pour que quelqu'un d'autre comprenne le code. Oui, cela peut parfois être nécessaire, surtout lorsque vous entrez dans des détails obscurs. Mais chaque fois que possible, j'essaie de tout garder dans le code lui-même afin qu'il ait une chance de rester à jour et facilement localisé. Dans ce cas, je privilégie l'accessibilité aux informations à l'expressivité de la documentation.

Dans nos projets, qui tournent autour de la recherche en économie financière quantitative, nous utilisons BEAUCOUP de mathématiques et nous suivons une combinaison de ce qui a déjà été publié:

1. Fournissez un lien vers la source principale que vous utilisez. Pour nous, la façon la plus simple de le faire est d'utiliser le BibTex-handle, qui est essentiellement un ID pour un document qui peut être consulté par toutes les personnes impliquées. Selon la source spécifique, nous ajoutons également régulièrement la référence de l'équation.

2. Fournissez des explications pour toutes les variables. Encore une fois, nous utilisons Tex pour cela si le papier original utilise des lettres grecques ou autres. La raison en est que, souvent, suffisamment de papiers et de livres utilisent des notations différentes. Si quelqu'un a besoin de retravailler les mathématiques, cela le rend beaucoup plus facile.

3. Essayez de coder l'équation en une seule pièce. Il est beaucoup plus facile de le reconnaître. NE postez PAS le Tex-Code de l'équation complète dans le code - soit l'équation est très courte, et la publication de tex est désordonnée et superflue, soit l'équation est énorme et le code tex est inutile, sauf si vous le compilez (utilisez un référence à la place). Le démontage d'une équation en petits morceaux rend très difficile la compréhension de ce qui se passe (si vous êtes bon en mathématiques au moins).

À mon humble avis, la réalisation la plus importante est que les formules dépendent souvent du contexte. Chaque article mathématique que je connais prend son temps pour configurer l'environnement du modèle; Tu devrais faire pareil.

le texte n'a pas le pouvoir expressif des mathématiques

Tu as raison. Puisque vous cherchez déjà un moyen de le faire en dehors du code, et Tex est un excès en plus d'avoir une courbe d'apprentissage abrupte, ma recommandation est la suivante:

Utilisez OpenOffice.org/LibreOffice Math Equation Editor.

C'est gratuit. C'est ouvert.

Vous pouvez l'utiliser soit visuellement, soit écrire les équations dans une langue spéciale.

Vous n'avez pas à apprendre la langue tout de suite car lorsque vous utilisez l'interface graphique, le "code" est généré dans un panneau pour que vous puissiez le voir.

Dans le panneau supérieur, vous pouvez "dessiner" les équations à l'aide d'une palette. Dans le panneau inférieur, la notation équivalente est générée. Vous pouvez le faire dans l'autre sens une fois que vous avez saisi la notation, en écrivant en notation dans le panneau inférieur et en voyant la sortie graphique dans le panneau supérieur.