How to document math formulations in scientific computing codes?

Question

I am writing the code relate to math.
There is some complicated math formulation in the project.
Directly writing the calculation code leads to hard understanding; thus I want to comment on the formulation.
I want the comment can be readable, and easy for understand.
I know we can save the formulation in another document file like latex or markdown. But it always leads to the code is modified but the document is not updated. At that time, the document is useless and even harmful.

Anton Menshov · Accepted Answer

I prefer using doxygen that supports C++ and LaTeX comments, both inline and as separate equations.
This way, you will keep your comments, including, say, the rigorous mathematical formulation of the algorithm, very close to the source code. The generation of the documentation can be included in the overall workflow (say, a Makefile or CMake target, depending on your assembly).
This does not automatically resolve the problem of outdated comments; however, it allows keeping them as close as possible, so, when modifying the source code, your math formulation is in the vicinity (if your functions & classes are properly designed to be of reasonable length). Thus, you are much more likely to edit the comment as well.
Also, check out the post What are good ways to document scientific software?, which has a slightly higher-level perspective on the issue of documenting scientific software.

How to document math formulations in scientific computing codes?

One Answer

Add your own answers!

Ask a Question