How would you describe math in comments?

Question

Well as the questions says...

An equation might be more meaningful in its math-notated form than it is in code. Being able to put math in comments could improve readabibity on my projects.

In .NET btw.

Answer 1

For plain comments I usually resort to LaTeX's or Word's syntax. But usually Word, since e. g. β is more readable than \beta. Since my source files are usually Unicode this doesn't pose a problem. Also I don't like too many braces around everything :-)

Sometimes I got bored with Javadoc and using much HTML to get formulas in Javadoc show up prettily but that doesn't help source readability (and exploits the fact that Javadoc only builds to HTML, no luck in .NET here).

I'd have written Pax's sample as

// Work out average as:
//   ∑(values)/|values|
// and distance between points as:
//   d = √( (x_1 - x_0)²  + (y_1 - y_0)² )
// and the following function:
//   f(x) = ax³  + bx²  + cx + d

I rarely use Unicode subscripts, though, as they aren't in every font, especially not those suitable for code :)

Answer 2

Y'know, this would be a great application for the Visual Studio extensibility that ScottGu showed at the last PDC (where he wrote a MEF plug-in to display comments in a different style).

You could write your mathematical comments using MathML, then knock up a plug-in that parses the markup and displays it like a proper equation.

This is more of a pie-in-the-sky comment than a real answer to your question, but I thought I'd post it to get people thinking. Maybe someone will do it one day! :)

Answer 3

I just use multiple lines to do it thus:

// Work out average as:  sum (values)
//                      --------------
//                      count (values)
//
// and distance between points as:
//           _______________________
//          /         2            2
//    d = \/ (x1 - x0)  + (y1 - y0)
//
// and the following function:
//
//             3     2   
//    f(x) = ax  + bx  + cx + d

No magic required for that at all. Don't you just love ASCII art?

Answer 4

Keep in mind what your audience is. The comment has to be meaningful to you months from now and to your (present and future) team-mates right now. Therefore, if the math-notation is perfectly comprehensible for you all, this could be fine; still, since I cannot know who will read that comment, I would add a textual representation or description.

Answer 5

For me, the easiest way to understand a complex math problem is to plug in some real numbers and to follow it through. Reading about how it works isn't enough unless I'm simply reminding myself what it does.

Using Nunit tests would be ideal for giving practical examples of how the complex math problem are used. Perhaps just use the comments to point out that there are unit tests they can walk through and where to find them.

Answer 6

Following up on @pax's answer to use ascii-art/plain text to render your equations (+1 by the way, pax):

Here's a quick list of shortcut keys for math-related characters:

° (degree) - Alt+0176

± (plus/minus) - Alt+0177

² (squared) - Alt+0178

³ (cubed) - Alt+0179

¼ (1/4) - Alt+0188

½ (1/2) - Alt+0189

¾ (3/4) - Alt+0190

Answer 7

I use latex: if it's simple you can see it anyway, and if it's complicated - cut and paste it in the nearest wordpress window, most times they parse correctly.

Answer 8

This was to be a comment of Matt's post, but my reputation is too low. I did something similar for LaTex. It is a Sandcastle build component that parses LaTeX embedded in XML comments and creates images that are added back to the documentation. It is a simple wrapper around mimeTeX. You can see the alpha code at: http://github.com/cuda/latex-sandcastle/

Answer 9

To make the ASCII rendering of mathematical fomulas a little easier there is asciiTeX. asciiTeX accepts LaTeX-style equations and prints them out in ASCII-art.