After much searching, I have failed to answer a basic question pertaining to an assumed known in the software development world:WHAT IS KNOWN:Enforcing a strict policy on adequate code documentation (be it Doxygen tags, Javadoc, or simply an abundance of comments) adds over-head to the time required to develop code.BUT:Having thorough documentation (or even an API) brings with it productivity gains (one assumes) in new and seasoned developers when they are adding features, or fixing bugs down the road.THE QUESTION:Is the added development time required to guarantee such documentation offset by the gains in productivity down-the-road (in a strictly economical sense)?I am looking for case studies, or answers that can bring with them objective evidence supporting the conclusions that are drawn.Thanks in advance!
Studies on code documentation productivity gains/losses
java;c#;c++;documentation;coding standards
The article Typographic style is more than cosmetic is rather old but it's very interesting: http://portal.acm.org/citation.cfm?id=78611.Being old, it does not include all the fancy stuff that would be possible these days but it shows clearly that code documentation does matter.For those who, like me, have no access to the ACM digital library, they created two groups of programmers and gave them the same code to study. The group A received just the code with the usual comments, group B received a pretty printed listing with table of contents, cross reference and all the niceties that were possible back in 1990. Then they asked the two groups to perform certain tasks on the code (e.g. extend a function, find a bug, ...) and scored them in term of speed and quality of the answers.To balance the group they had the same number of expert and junior programmers.Well, it turned out that group B (the one with pretty printed listing) cosistently scored better then group A in numerous tests. And, on specific cases, only the most expert ones of group A managed to surpass the junior programmer of group B.The article says more but this is what I can recollect from memory (I should still have the printed article somewhere).