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?

  • 1
    This would obviously depend a great deal on whether one was talking about mathematical complexity or architectural complexity. They're not documented in at all the same manner. Which is it? May 14, 2012 at 7:03
  • 2
    related: Where should a programmer explain the extended logic behind the code?. I especially like the tests-as-a-doc approach suggested in one of the answers.
    – gnat
    May 14, 2012 at 10:10
  • 1
    @Gnat, why thanks. I think that overall, my answer to that question would work for this question too.
    – Mark Booth
    May 14, 2012 at 12:34
  • @MarkBooth right, it was mostly your answer I had in mind when suggesting related question. Answer is good generally, but the point about tests especially rung a bell as I did use it once for one particularly complicated algorithm implementation
    – gnat
    May 14, 2012 at 12:39

3 Answers 3


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.


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.


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.

  • 1
    "If a jr. dev is going to be required to maintain the code..." In my experience it's better to just assume that everyone reading your comments is a jr. dev. If they aren't then they wouldn't be reading your comments. Even if they are not jr. and are still reading your comments, jargon and assumptions lead to miscommunication. Finally...most devs, like every other field known to man, get through life not really giving a damn and never really get a whole lot better than "jr". May 14, 2012 at 7:07

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.