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.

  • 1
    $\begingroup$ If your text editor and compiler don't complain about non-standard unicode characters, you can directly insert mathematical symbols into a comment for convenience. I use the :digraph command in vim to write out formulations in the comment preceding a function that implements a complicated calculation. Of course, the comment does not get typeset, so you're still a bit limited in what you can do. $\endgroup$ – smh Jul 13 '20 at 13:14

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.


Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.