コードでの数学ロジックの文書化
まれではありますが、コードに数学ロジックを含める必要がある場合があります。使用される概念はほとんど非常に単純ですが、結果のコードはそうではありません-目的が明確でない多くの変数、およびそれほど明白な意図のないいくつかの操作。 waaaay実際の数学の問題よりも理解するのが難しいというだけで、コードが読み取り不可能または保守不可能であるという意味ではありません。わかりにくい部分はコメントにしようとしていますが、コーディングするだけで同じ問題がありますテキストには数学の表現力がありません。
複雑なコードの一部、好ましくはコード自体の背後にあるロジックを説明する、より効率的で理解しやすい方法を探しています。私はTeXを検討しました-ドキュメントを書いて、それをコードとは別に生成しました。しかし、私はTeXを学ぶ必要があり、ドキュメントはコード自体には含まれません。私が考えたもう1つのことは、紙/ホワイトボードに書かれた数学表記、方程式、図の写真を撮り、それをjavadocに含めることです。
より簡単で明確な方法はありますか？
追伸変数にわかりやすい名前（t1ではなくtimeOfFirstEvent）を付けると、実際にはコードが冗長になり、読みにくくなります。
そのような状況で行うべき正しいことは、アルゴリズム、式などをexactlyで実装することです（プログラミング言語で許可されている限り）現実のソースと同じ変数名。その上に、「[Knuth1968]で説明されているレーブンシュタイン距離計算」のような簡潔なコメントを付けてください。引用は、数学の簡単にアクセスできる説明にリンクしています。
（もしあなたがhaveのような参照をしなくても、あなたの数学が健全で有用であるなら、多分あなたはそれを自分で公開することを考えるべきです。ただ言うだけです。）
そのようなアルゴリズムを実装しなければならなかったとき、私が行うことはいくつかあります。
可能な限り、アルゴリズムを独自のメソッドまたはできればクラスに分離します。現在のプロジェクトには、独自の同等の
Mathクラスがあり、複雑なアルゴリズムを追加できます。一般的な頭字語や用語の省略形など、一般的な用語でアルゴリズムが行うことになっていることの要約を提供します。これはメソッド自体で行うので、コードと一緒に使用します。
技術的/数学的な用語でアルゴリズムの概要を提供し、私が知っている外部参照をすべて含めます。繰り返しますが、これはメソッド自体で行うため、関連性を保つ可能性が高くなります。この場合、プレーンテキストは適切ではないので、数学用語をできる限り引用し、その横の括弧付きのコメントで明確にします。たとえば、
x^y (x raised to the power y)アルゴリズムをコンポーネントに分解する方法を文書化し、各変数がアルゴリズムで何を表すかを示します。例えば。
t1 is time of first eventアルゴリズムをコード化し、複雑な部分にコメントを付けます。基本的に、アルゴリズム自体の中で明白ではない、または簡単ではないステップを実行する任意の場所にコメントを追加します。特に、明白でないショートカットと、実装内で許可される理由についてコメントしていることを確認します。
アルゴリズムの動作を検証するいくつかの単体テストを作成します。
最後に、本当に、本当に、本当に複雑な場合は、そのプロジェクトの残りの時間、そのコードを所有しているという事実に自分を辞任します。
他の誰かがコードを理解するのに外部ドキュメントに依存するのは好きではありません。はい、特に難解な詳細に入るときに必要になる場合があります。しかし、可能な限り、コード自体の中にすべてを保持するようにしています。そうすれば、コードが更新されたままになり、簡単に見つけられる可能性があります。この場合、ドキュメントの表現力よりも情報へのアクセシビリティを重視します。
定量的金融経済学の研究を中心に展開している私たちのプロジェクトでは、たくさんの数学を利用し、すでに投稿されているものの組み合わせに従います。
使用しているメインソースへのリンクを提供します。私たちにとって、これを行う最も簡単な方法は、BibTexハンドルを使用することです。これは、基本的には関係者全員が検索できる論文のIDです。特定のソースに応じて、式の参照も定期的に追加します。
すべての変数の説明を提供します。この場合も、元の紙にギリシャ語やその他の文字が使用されている場合は、Texを使用します。この理由は、多くの場合、十分な数の論文と本が異なる表記法を使用しているためです。誰かが数学をやり直す必要がある場合、これはそれをずっと簡単にします。
方程式を1つにコード化してみます。そのように認識する方がはるかに簡単です。完全な方程式のTex-Codeをコードに投稿しないでください-方程式が非常に短く、texの投稿が乱雑で不必要であるか、方程式が巨大であり、texコードがコンパイルされない限り、役に立たない（使用する代わりに参照）。方程式を細かく分解すると、何が起こっているのかを理解するのが非常に難しくなります（少なくとも数学が得意なら）。
私見、最も重要な認識は、式はコンテキストに依存することが多いということです。私が知っているすべての数学の論文は、モデルの環境をセットアップするのに時間がかかります。同じことをする必要があります。
テキストには数学の表現力がない
あなたが正しいです。あなたはすでにコードの外でそれを行う方法を探していて、Texは急な学習曲線を持っていることに加えてやり過ぎなので、私の推奨は次のとおりです。
OpenOffice.org/LibreOffice Math Equation Editorを使用します。
それは無料です。開いています。
視覚的に使用することも、特別な言語で方程式を書くこともできます。
GUIを使用すると、「コード」がパネルに生成されて表示されるため、すぐに言語を習得する必要はありません。
上部パネルでは、パレットを使用して方程式を「描く」ことができます。下のパネルでは、同等の表記が生成されます。表記法を理解し、下のパネルに表記法で書き込み、上部のパネルにグラフィック出力を表示すると、逆の方法でそれを行うことができます。
