コードで数学ロジックを文書化する

まれですが、コードに数学ロジックを含める必要があります。使用される概念はほとんど非常に単純ですが、結果のコードはそうではありません-不明な目的を持つ多くの変数、およびそれほど明白ではない意図のある操作。コードが判読不能または保守不能であることを意味するのではなく、実際の数学の問題よりも理解が難しいというだけです。私は理解が最も難しい部分にコメントを付けようとしますが、それらをコーディングするのと同じ問題があります- テキストには数学の表現力がありません。

複雑なコードの一部、できればコード自体の背後にあるロジックを説明する、より効率的で理解しやすい方法を探しています。私はTeXを検討しました-ドキュメントを書き、コードとは別に生成します。しかし、それから私はTeXを学ぶ必要があり、ドキュメントはコード自体にはありません。私が考えたもう1つのことは、紙/ホワイトボードに書かれた数学表記、方程式、図の写真を撮り、それをjavadocに含めることです。

より簡単で明確な方法はありますか？

PS 変数に（のtimeOfFirstEvent代わりにt1）わかりやすい名前を付けると、実際にはコードがより冗長になり、読みにくくなります。

そのような状況で行う正しいことは、アルゴリズム、式、または主要な実世界のソースとまったく同じ変数名を持つものを実装することです（プログラミング言語がこれを許可している限り）。 「[Knuth1968]で説明されているレーベンシュタイン距離計算」のようなもので、引用が簡単にアクセスできる数学の説明にリンクしています。

（もしあなたがそのようなリファレンスを持っていないが、あなたの数学が健全で有用であるなら、多分あなたはそれを自分で公開することを検討すべきです。ただ言ってください。）

そのようなアルゴリズムを実装しなければならなかったとき、私はいくつかのことをします。

1. 可能な限り、アルゴリズムを独自のメソッドまたはできればクラスに分離します。私の現在のプロジェクトにはMath、複雑なアルゴリズムを追加する独自の同等のクラスがあります。

2. アルゴリズムが一般的な頭字語や用語への略語の参照を含む一般用語で行うことになっているものの概要を提供します。私はメソッド自体でこれを行うので、コードと一緒に生きます。

3. 技術的/数学的な用語でアルゴリズムの概要を提供し、私が知っている外部参照を含めます。繰り返しますが、私はメソッド自体でこれを行うので、関連性を保つ可能性が高くなります。この場合、プレーンテキストはあまり良くないので、できる限り数学用語を引用し、その横にある括弧付きのコメントで明確にします。例えば、 x^y (x raised to the power y)

4. アルゴリズムをコンポーネントに分解する方法を文書化し、各変数がアルゴリズムで何を表すかを示します。例えば。t1 is time of first event

5. アルゴリズムをコーディングし、複雑な部分にコメントを付けます。本質的に、アルゴリズム自体の中で明らかでなかった、または簡単ではなかった一歩を踏み出す場所にコメントを追加します。私は特に、明白でないショートカットと、それらが実装内で取ることができる理由についてコメントすることを確認します。

6. アルゴリズムの動作を検証する単体テストを作成します。

最後に、それが本当に、本当に、本当に複雑な場合は、そのプロジェクトでの残りの時間はそのコードを所有しているという事実に自分自身を辞任します。

他の誰かがコードを理解するために外部ドキュメントに頼るのは好きではありません。はい、特に不可解な詳細を取得する場合に必要になることがあります。しかし、可能な限り、すべてをコード内に収めるようにして、更新された状態を保ち、簡単に見つけられるようにします。この場合、ドキュメントの表現力よりも情報へのアクセシビリティを重視します。

量的金融経済学の研究を中心としたプロジェクトでは、多くの数学を利用し、すでに投稿されているものの組み合わせに従います。

1. 使用しているメインソースへのリンクを提供します。私たちにとって最も簡単な方法は、BibTexハンドルを使用することです。これは、基本的に、関係者全員が参照できる論文のIDです。特定のソースに応じて、方程式参照も定期的に追加します。

2. すべての変数の説明を提供します。繰り返しますが、元の紙がギリシャ語または他の文字を使用している場合、そのためにTexを使用します。その理由は、多くの場合、十分な数の論文や本が異なる表記法を使用しているためです。誰かが数学をやり直す必要がある場合、これは非常に簡単になります。

3. 方程式を1つのピースにコード化しようとします。そのように認識する方がはるかに簡単です。完全な方程式のTex-Codeをコードに投稿しないでください-方程式が非常に短く、texが乱雑で不必要であるか、方程式が巨大で、texコードはコンパイルしない限り役に立たない（代わりに参照）。方程式を小さな断片に分解すると、何が起こっているのかを理解するのが本当に難しくなります（少なくとも数学が得意な場合）。

私見、最も重要な認識は、式がしばしば文脈に依存するということです。私が知っているすべての数学論文は、モデルの環境をセットアップするのに時間がかかります。同じことをする必要があります。

テキストには数学の表現力がありません

あなたが正しいです。あなたはすでにコードの外でそれを行う方法を探しており、Texは急な学習曲線を持つことに加えてやり過ぎですので、私の推奨事項は次のとおりです：

OpenOffice.org/LibreOffice Math Equation Editorを使用します。

それは無料です。開いています。

視覚的に使用するか、特別な言語で方程式を書くことができます。

GUIを使用すると、パネルに「コード」が表示されるため、すぐに言語を習得する必要はありません。

上のパネルでは、パレットを使用して方程式を「描く」ことができます。下のパネルでは、同等の表記が生成されます。表記法を理解したら、逆の方法でそれを行うことができます。下のパネルに表記法を書き、上のパネルにグラフィック出力を表示します。