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.

Every library, open-source project, and SDK/API I've ever come across has come packaged with a (usually large) documentation file, and this seems contradictory to the wide-spread belief that good code needs little to no comments. What separates documentation from this programming methodology?

a one to two page overview of a package seems reasonable, but elegant code combined with standard intelisense should have theoretically deprecated the practice of documentation by now IMO.

I feel like companies only create detailed documentation and tutorials because its what they've always done.

Why should developers have to constantly be searching through online documentation in order to learn how to do things when such information should be intrinsic to the classes, methods and namespaces?

share|improve this question

closed as not a real question by Jim G., GrandmasterB, littleadv, thorsten müller, JeffO Oct 7 '12 at 14:20

It's difficult to tell what is being asked here. This question is ambiguous, vague, incomplete, overly broad, or rhetorical and cannot be reasonably answered in its current form. For help clarifying this question so that it can be reopened, visit the help center.If this question can be reworded to fit the rules in the help center, please edit the question.

7  
...what planet are you from? –  ZJR Oct 7 '12 at 4:09
1  
Good code needs little to no comments? I have never heard about such a belief. Except from lazy people or people who consider their code to be good (their code is usually not). Once they're tired of answering questions about it, they change their mind. –  littleadv Oct 7 '12 at 4:11
4  
"Documentation is like sex. When its good, its very very good, when its bad, its better than nothing." –  Burhan Khalid Oct 7 '12 at 5:03
1  
@littleadv So you have heard it, then? I've heard it too. That would be how this question came about :) –  romkyns Oct 7 '12 at 9:10

4 Answers 4

up vote 3 down vote accepted

To have no documentation at all and to think that IntelliSense is all you need to understand the finest and subtlest details of what each class/method does, is illusory.

There are of course some very simple cases — for example, if a List class has a Count property, what could that property possibly return except the obvious. But a very significant amount of methods have corner-cases or behavioural properties that need to be documented for the benefit of the API user.

Let’s take an example:

public static TabPage ContainingTabPage(this Control control);

Do you think it’s obvious what the method does? Well, its intention is certainly clear, but... what if the control is not contained in any TabPage? Does it return null or does it throw? What if it’s in multiple nested TabPages? — Fortunately, the documentation answers these questions: If this control is located within a TabPage, returns the first TabPage found by iterating recursively through its parents. Otherwise returns null. What would the method need to be called to make this documentation redundant? InnermostContainingTabPageOrNull()? That does not really contribute to code readability.

Or take something like this:

/// <summary>
/// Returns the smaller of the three IComparable values. If two values are
/// equal, returns the earlier one.
/// </summary>
public static T Min<T>(T val1, T val2, T val3) where T : IComparable<T>;

In the majority of cases the second sentence in the documentation is irrelevant but does no harm. In the few cases where it does matter, it can save you a lot of time — if you don’t have the source code, you’d have to find the answer by experiment. In this case the experiment is easy, but imagine the method is about concurrency and you’re wondering about its thread safety or race conditions...

Another example: take an XML serializer. That’s simple, you might think, just have a XElement Serialize<T>(T) and a T Deserialize<T>(XElement) method and it’s totally clear what they do! Uhm, well, except... how does it serialize dictionaries? How does it handle interfaces? Does it preserve object identity? Does it cope with cyclic references without going into infinite loops? How does it behave when faced with the challenge of serializing delegates, native resources, remoting proxies? What exception types does it throw in which situations?

Only having two methods does not mean the process of serializing data is simple. Consequently, our custom XML serializer has a big thumping documentation block on the class which describes, in detail, all its features and all its limitations; what kinds of classes it can serialize, what assumptions it makes and what exceptions it throws; the custom attributes you can use to modify its behaviour; and, perhaps most importantly, what the fundamental design ideas behind it are and what use-cases it intends to cover (so that if your intended use-case is sufficiently different, you know you may be better off choosing a different serializer).

Now, with all that said, I think there is something to be said about quality vs. quantity. A lot of hobby-made libraries come with extra HTML files or other documents containing heaps of low-quality documentation when they could be more useful with less but better documentation. Good documentation needs to fulfill two important functions:

  • What does this class/method do? — This one is easy, just document each class/method.

  • How do I do X? — This one is hard. It may not be obvious to the API user what the method or class they need is called. To cover such cases, it often helps if the documentation for one method links to another (e.g. “if you are trying to do X, prefer to use M”) or the documentation for a class mentions all of the other classes with which it interacts (e.g. our above-mentioned XML serializer lists all the custom attributes that influence it). Some small code examples for common scenarios can be helpful, but only if they’re not trivially obvious.

There must be a small set of places to look for the answer. If the API user feels that they have to read pages after pages of irrelevant stuff only to ascertain that the answer they’re looking for isn’t in it, then the documentation is too badly structured and the API user may as well not bother reading it if it’s easier and faster to just ask on StackOverflow.

So, in summary: No, extensive documentation is not a code smell at all. Certainly you can’t improve the code simply by removing the documentation. But it may be a documentation smell. There is good documentation and there is bad documentation, and in some cases bad documentation may be improved by trimming it. Adding more documentation can make the documentation worse. Quality of documentation is not measured by number of words any more than code quality is measured by lines of code.

share|improve this answer
    
Your list count example is a perfect counterexample: in some cases a linked-list count may not be a constant-time operation but a linear-time operation, so I'd like the documentation to tell me whether it's being cached in some way and what I can expect! –  Joris Timmermans Nov 13 '12 at 13:07

For libraries and public APIs, good documentation with sample code makes adoption much easier. The documentation does not have to be extensive (javadoc-style docs on every method are often useless), but should provide a to-the-point introduction on basic concepts and structure, as well as examples on a proper way to do common tasks with the API.

There are design decisions, patterns and recommended practices that a user cannot easily glean within a reasonable timeframe just by looking at the code, unless the API is extremely simple (which is not always possible).

share|improve this answer

I'm not sure what open source libraries you've been looking at, because most have crap for documentation. That said...

First, before I decide I even want to use a library, I'd like to see some documentation explaining whether it will do exactly what I need it to do--I'd rather not have to download and search through source code to figure it out.

It's also a heck of a lot easier to search through a documentation file for desired functionality than it is to search source code. I don't care how clearly you (think you've) named your classes, someone is going to not realize that the Fuu class really does Foo. An explanation written in English is going to help me to work this out.

API documentation in the form of javadoc (for example) can also be linked directly to the source code within IDEs (such as Eclipse), which also can make working with the library a lot easier.

So no, extensive documentation is a GOOD thing. You don't have to read it if you don't want to, but I do.

share|improve this answer
    
Couldn't agree more. I don't even want to download and look at something unless I've had the opportunity to read the documentation and know for sure whether it fits my needs or not. –  Carson63000 Oct 7 '12 at 8:13

Chiming in with the other two responses (+1 for both), good APIs are a nice to have, but good documentation is essential. Perhaps documentation isn't needed for a very simple package, one in which each object / each function stands on its own, and each object / each function does exactly what one would expect. A simple mathematical matrix/vector package, for example, might be self explanatory. Then again, maybe not. Even those simple packages oftentimes come with extensive documentation. Which matrix decomposition is best for this situation? For that one? Naive matrix operations inevitably thrashes memory. A good package will tell me how to use parts of the package in combination so as to avoid these problems. And that's a simple package.

In a toy package for a toy problem, objects and functions don't interaction, there are no dependencies, and interfaces are blindingly obvious just from the API. Life usually isn't that simple, and neither are most software packages.

share|improve this answer

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