If I have a piece of code that is mathematically or structurally quite complex and irreducibly so, how would I go about documenting this piece of code? In particular, how can I ensure that someone who may not have the mathematical or architectural skills that I do can understand it from the documentation? Should I document all of the math too? Link to a tutorial? Do some visual aid linkage in the case of complex structures?
Documentation – How to Document Complex Code Structures
documentation
Best Answer
This really depends on how complicated the code and math is. The code itself should - as always - be as self-documenting as possible. Name variables correctly, implement logical and concise methods (rather than mega-functions), add in-line documentation where appropriate (i.e. when it is not obvious what the code is actually doing).
If you're using a non-obvious algorithm, add a link to a reference it the source. This is a reasonable practice because it gives the developer a very quick way to find out what you're doing. As I said, this is useful if it's a non-obvious yet complex algorithm. This should prove that (a) you are doing something that makes sense, and (b) someone has demonstrated that it works.
A good example is some work I did around fuzzy text matching. I did substantial research into algorithms and implemented what is known as 'Smith-Waterman algorithm' (which is actually used for DNA sequences, but applies to 'matching' generally). So instead of simply implementing the algorithm, I found references online and included a link or two. As above, this demonstrates that (a) my algorithm matches the published algorithm, and (b) the algorithm has been reviewed and shown to work.
However this doesn't necessarily explain how the code works, and what the various classes are supposed to do. When you go to write some 'real' documentation - a developer guide to the system - you should explain what you've done and provide enough information for future support. In my opinion this document should be readable by a technically agnostic person; it doesn't need to be 'dumbed down' but it should exclude jargon and not rely on assumed knowledge.