How do I document necessarily complex code structures?

Question

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?

Answer 1

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.

Answer 2

Comments surrounding the source is the first thing you should do. This makes sure that there is a direct link to the documentation right by the code. If the documentation is very complicated, consider posting only an abstract in comments, and then a link to some external document that contains a more complete description of the architecture/complex algorithm. If it's not too complicated, however, consider including all the documentation in one place. This will maximize the likelihood of your code/documentation staying in synch and are read together.

Answer 3

Document the code to the extent your team/company needs it. If a jr. dev is going to be required to maintain the code, you may have to go into detail about some of the math. This is a management decision and they have to give you the necessary time.

I don't think you have to document the code so much that you account for being replaced by a lesser developer. If that is a concern, you need to be given time to document.

You shouldn't have to do the web search for them.