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.

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!

share|improve this question

migrated from stackoverflow.com Feb 1 '11 at 19:30

This question came from our site for professional and enthusiast programmers.

    
If you're looking for opinions, this belongs on programmers.se. –  David Thornley Feb 1 '11 at 19:25
    
I disagree that it should have been moved. To clarify, I am STRONGLY looking for any studies that have been done. –  J T Feb 1 '11 at 19:36
    
Edited. Could a moderator please migrate this back to Stack Overflow where this question will enjoy a much broader audience thus increasing its chances. –  J T Feb 1 '11 at 19:55
8  
I don't think that this is a suitable question for SO as it's not a coding question, but a question about coding. I actually think that it's a perfect question for Programmers'. –  ChrisF Feb 1 '11 at 20:00
add comment

9 Answers

up vote 6 down vote accepted

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).

share|improve this answer
    
+1 for an actual study. –  Robert Harvey Feb 1 '11 at 22:48
add comment

For me at least, it seems obvious that readable code is worth much more than documentation which only serves to make up for poorly written code. I tend to consider comments in code as a challenge to see if I can remove the comment by rewriting the code and make it more self explaining.

I can't back that up with any hard evidence, except well, common sense.

share|improve this answer
    
It makes economical sense to have only to read through some javadoc to use a method instead of having to read through the whole method –  Heiko Rupp Feb 1 '11 at 21:25
2  
@Heiko: If you can't figure out what a functions does from the function name and the parameter names, it's time to rename them. –  Sjoerd Feb 1 '11 at 21:34
3  
I agree with this answer, but sometimes you need to add documentation for things like: what are the valid return values? What are the valid input values? How does this fit in to the overall framework of the program? What are the requirements of the method? –  DominicMcDonnell Feb 1 '11 at 21:41
1  
@Sjoerd: That can give you a broad overview of what the method does, but it doesn't tell you everything. Allowable input values, what it can return, how it handles errors, what prior state it expects etc. are all impossible to impart just by choosing appropriate method and parameter names. –  Anon. Feb 1 '11 at 21:57
    
@Anon: If it requires a prior state, it's time to redesign. Errors are handled by throwing exceptions (and Java will list the types - C++ and C# programmers don't care about the exception type so no need to document it). About the only thing important is whether nulls are accepted or returned (which in C++ can be signaled by using references or pointers - Java is less clear and required documentation in this case). And even in that case, names can help: e.g. FindFoo() returns null if not found, GetFoo() will throw an exception if not found. –  Sjoerd Feb 1 '11 at 22:36
show 2 more comments

I don't have any studies to quote, but I do have a simple rule: if I come back to my code two weeks later and can't immediately figure out what I did, it either needs more comments, or needs to be simplified.

Certainly, how your code works should be documented by the code itself. But time spent writing comments that carefully and succinctly explain why your code is written the way it is almost certainly pays for itself in the long run, even if you are the only person who maintains the code.

The lifetime of a piece of software will be spent mostly in the maintenance stage, so anything that helps the programmer coming after you to understand what is happening will almost certainly provide financial returns, because it helps that developer get up to speed faster.

share|improve this answer
add comment

On any API that is slightly non trivial documenting the API in the code is just about useless. This is because the power in the API comes from how it works together as a whole unit (not how individual methods/objects work).

Thus more helpful than the true documentation is a cookbook-like document that explains the expected usage patterns of the API, and examples of how to solve some obvious situations (that use the majority (not 100%) of the API).

share|improve this answer
    
+1 for usage patterns. If I had nothing else to work with, code samples would suffice. –  Robert Harvey Feb 1 '11 at 22:49
    
+1 for the excellent point that perhaps code examples are MORE important than a clean API. –  J T Feb 2 '11 at 20:08
    
@J T: I like the sentiment but I would rather rephrase it: Clean common usage scenarios are more important than a clean API –  Loki Astari Feb 2 '11 at 20:29
add comment

The decision of whether a given method is, without tools that have probably not been invented yet, too subjective to require that documentation be written.

Any best-guess practices, such as "all public methods" or all classes in a given package, etc., may help but are too rough to recommend beyond specific use cases.

My suggestion: Teach your developers good practice, how to identify methods that are important to document (formal or informal API, commonly used, stub methods, complex or esoteric) and let them govern themselves.

(Closely related: Can there be too much uniformity in coding standards?)


Apologies that I don't have any studies to quote, but I'm suspecting that this is a problem where any attempts to measure it would affect the outcome too greatly to draw general conclusions.

share|improve this answer
add comment

I think we need to separate "regular" code from public APIs in this respect. For regular code I have come to strongly agree with most of the other answerers in that code should be self documenting and read almost like prose. If my code is not like that, it is usually my fault, so rather than documenting, it should be refactored. Small methods which do only one thing at a time, working on a single level of abstraction, having a correct and descriptive name, can go a great way towards achieving this.

The problem with comments is that they rot. As soon as you add a comment, it starts to live a life independent of the code it accompanies. How big the chance is that the next developer who modifies the code will dutifully update the related comment(s) too? In my experience, close to zero. The end result after a few modifications is that the comment puzzles or misleads people instead of helping them.

Possible exceptions are performance optimized code, or using a specific algorithm. In this case it is useful to add comments to describe why the code looks like it is, a reference to the algorithm etc.

The seminal work on this topic is Clean Code.

OTOH a public API should really be well documented in Javadoc too. Since it may be used by countless total strangers with wildly varied skills and assumptions, one has to do any precautions to make it as simple and unambiguous to use as possible. That is still largely a question of proper API design, but there is an important role for documentation too.

share|improve this answer
    
+1 for the excellent point about comment "rot" –  J T Feb 2 '11 at 20:02
add comment

The issue is whether you save time by documenting your code versus every subsequent developer having to try to figure out what is does. If your code flies through code review without anyone bringing up any questions about what it does, you are probably in good shape. It's not too hard to describe the assumptions you make about inputs. Let's say your method takes an integer object and returns a string object. Can the int be null? Is there a min/max value (besides integer.MinValue/MaxValue)? Can it return an empty string or null? Does it throw any exceptions? Of course anyone can find these by inspection, but if enough other devs are going to be using your code, saving each a few minutes is well worth your time. Also, it gives testers a leg up on creating tests to confirm your code.

share|improve this answer
    
+1 for the idea to use code review as the mechanism to detect if code is verbose and clean enough or if it requires. Also excellent point about how a clean API helps testers write unit tests –  J T Feb 2 '11 at 20:05
add comment

This is certainly an interesting topic as there has always been arguments whether developer should spend time creating or maintaining documents or not but fact is that code should be well written and very well commented, this way when developer re-visits the code than he or she does not have to spend time pondering on how code was written and what was it suppose to do in the first place moreover if new team member joins the team than he can also understand the functionality and working of code as it has been clearly documented.

So code should be very well commented and so should be self-documented code which does not require any external documentation.

share|improve this answer
add comment

In my career, I've seen code with varying levels of documentation and quality (note that documentation and quality are orthoganal concerns). I'd prefer the time spent on documentation to be used on improving quality. For the simple case there are tools like GhostDoc that can look at a function and generate doc comments for you. If GhostDoc can generate a meaningful comment that says what your function does, then you've obviously achieved the goal of having well-named functions.

In many cases, GhostDoc can't even begin to tell you what a function really does. Your time is better spent addressing that issue and (maybe) using ghostdoc to auto generate your code.

See Clean Code and PPP from Bob Martin for a deeper discussion.

share|improve this answer
add comment

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.