What to use when text comments just wont do?

Question

Hi -

I'm writing a graphics application that's maths and geometry intensive. Frequently, I find that although I comment my code as best as I can, after sometime of working on some other part of the app, the previous comments become are hard to understand when I revisit it (usually for debugging). I'm starting to think that there are cases where text comments just won't do, and diagrams are required -- lots of them.

I suspect this problem is not new, and I would like to know how what techniques other experienced developers/teams use. I'm getting to the point many of my methods probably require at least 2-pages of notes and diagrams to describe. For example, one method that I debugged yesterday handles five different ways by which a line can intersect a triangle edge. I've commented the method as best as I can, but I'm worried that my well-crafted comments won't make sense in 4 months when I have to debug the method.

Thanks,

Olumide

Answer 1

It is not uncommon to include a readme file or other type of help file with your program. For example, those other types could be PDFs that include diagrams. You can annotate your code to refer to the included help files.

Answer 2

In such cases, I refer to an external document (pdf most likely) which describes the problem with graphics. I most likely use the <see> tag in the comment section (.NET world). See http://msdn.microsoft.com/en-us/library/acd0tfbe.aspx

Answer 3

If the algorithm is described somewhere on the Web, include a URL in the comments to supplement the comments in the code.

And there's always ASCII art!