Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question
    
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? –  Crazy Eddie May 14 '12 at 7:03
1  
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 '12 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 '12 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 '12 at 12:39

3 Answers 3

up vote 6 down vote accepted

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.

share|improve this answer

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.

share|improve this answer

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.

share|improve this answer
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". –  Crazy Eddie May 14 '12 at 7:07

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.