Should all public methods of an API be documented?

Question

When writing "library" type classes, is it better practice to always write markup documentation (i.e. javadoc) in java or assume that the code can be "self-documenting"? For example, given the following method stub:

/**
 * Copies all readable bytes from the provided input stream to the provided output
 * stream.  The output stream will be flushed, but neither stream will be closed.
 *
 * @param inStream an InputStream from which to read bytes.
 * @param outStream an OutputStream to which to copy the read bytes.
 * @throws IOException if there are any errors reading or writing.
 */
public void copyStream(InputStream inStream, OutputStream outStream) throws IOException {
    // copy the stream
}

The javadoc seems to be self-evident, and noise that just needs to be updated if the funcion is changed at all. But the sentence about flushing and not closing the stream could be valuable.

So, when writing a library, is it best to:

a) always document
b) document anything that isn't obvious
c) never document (code should speak for itself!)

I usually use b), myself (since the code can be self-documenting otherwise)...

Answer 1

I'd say a, in that when someone who is obtuse is reviewing or modifying your code, nothing is left for interpretation, even if without the documentation, you think it's perfectly clear.

Answer 2

a) Always document.

This will allow you to use automated tools to generate web-based, paper-based, etc. documentation, which may be invaluable to users who don't always have the source code in front of them.

Answer 3

I choose a, purely because when I investigate a class I like to see documented public methods (in javadoc or similar). It makes some things slightly clearer. But each to their own.

Answer 4

Every public method should be documented.

Answer 5

This is where I would normally chime in with the "both-ways-uphill when I was a kid" mantras about documenting only when your boss asks you to BUT ... lately I have changed my tune. I think it is crucial to provide thorough documentation of every public method when you are working on an open-source project, a library to be commonly called, or know ahead of time that someone else will have to work closely with the interfaces you are providing.

Documentation makes for maintainable code, but, like anything, you can overdo it and spend time writing comments and POD and wikis when you should be working on adding features and getting unit tests to pass. This is addressed in the Agile Manifesto (ie: face-to-face communication is better than documentation and so on up the ladder of interface methods).

Answer 6

a)

If it's a method, there are always some little details that matter, for example the ones you provided regarding flushing and closing the streams. For example a method "String getFileExtension(String filename)" seems to not need documentation, but what if "filename" doesn't have an extension? That answer should be documented.

If it's a type, it should mention other types with which it collaborates, and how it does that. This helps a user to navigatethe documentation in your desired way and not just browse the documentation without any direction.

Answer 7

a)

As others have mentioned, you can generate documentation and it helps with maintenance.

Also, Intellisense benefits from telling what the method/property does/is.

Answer 8

a)

An additional benefit of up-front thorough documentation is to help prevent changes in the method behaviour over time. In the example, you cite the sentence about flushing and not closing the stream could be valuable - I'd say this level of detail is essential semantics which a user of the method needs to know. If this wasn't documented, then a later implementation of the API may not do the flush which could lead to unpredicatable results for the user of the method.

Answer 9

Especially for APIs, every public method (and field) should indeed be documented. Furthermore, the documentation for the method should be clear enough and informative enough that the available information leaves no room for ambiguities.

A good example of an API is the Java API Specification. Notice from the title of the document that it is an specification. I believe that a documentation should be thorough enough to consider it as a specification.

For the most part I see the Java API Specification as an excellent example, however, there are some parts that I noticed are not as well-documented and/or informative. Take for example the DropTarget class. It has a method called clearAutoscroll(), and the javadoc for that method is:

clearAutoscroll

protected void clearAutoscroll()

clear autoscrolling

Nothing is more frustrating than documentation for an API that is uninformative like this. Worst of all, the provided information is not even a sentence! Be sure that the documentation provided for all public fields and methods are informative enough that the users of the library don't end up irritated rather than being informed.

Answer 10

So, my opinion is that if you are developing an API for others to use, it ought to be clear as to the intent of every method, property, etc.

I should be able to look at a method and know:

• what it returns, if anything, and if that return value is in a particular unit (feet, meters, degrees, etc.) then it should be clear. The user should have to guess whether your method returns celsius or Fahrenheit or Kelvin.
• what parameters it takes and what units those are in, if any
• The purpose of the method and ranges on those parameters and return values, if that makes sense
• anything else that isn't obvious to the reader

As a user of many APIs, I've seen the good, bad and ugly. As a writer of many, I've learned my lesson early on about not being clear and specific when providing an interface, particularly when I had to use a library I wrote several years prior and had to dig through the code to determine exactly what I was thinking when I had written it.

I don't think you need to go overboard on documentation and think that well picked methods, argument names, etc. go a LONG way toward readability. But when you are writing a method, it takes only a few seconds - maybe a minute tops - to document it. There's no compelling reason I can see not to make the public interface clear and to document it where it needs it. Perhaps if it is a 'throwaway' library.... but I don't write too many of those.

Just my two cents.

Answer 11

Anything publicly accessible, whether method, field, constant, or what-have-you, should be documented to the point that a user or developer (that's an inclusive or, btw) will be able to come along, years later, and have all the information they need to make use of the documented object. Document prerequisites to use, the purpose, anything thrown, and what changes after use.

Be clear and specific, leave nothing as guesswork. If you're so inclined, show the declaration of what you are documenting to someone not involved with your project, and ask them if there's anything missing. Take notes, and make sure their concerns are covered.

Tout le monde says that code should be good enough documentation, but that's a myth. Not everyone sees the code, or realizes what neat tricks you've worked in it. Therefore, document everything that others might see, and even things that they won't. Your users, fellow developers, and yourself in a couple years will thank you for it.

Answer 12

Always Document.

What's obvious to you may not be obvious to others, especially if they're looking at the situation from a different point of view (non-coders, beginners, users not familiar with your language structure)

Also for completeness of documentation.

Answer 13

Sorry to Parrot, but Always document.

Always document, even your private functions. I have forgotten everything I know several times. But in the beginning I commented everything so at least that was easy to figure out again. When I made some small libraries I documented all the functions for the team I was on without some of the notes I made, the internal workings would have been completely impossible to decipher.

I have written ridiculously complicated code, such that, that to none of my teammates could understand. None thought it sloppy or inelegant but before a detailed explanation (taking several hours) none could follow the logic. after I wrote it once on paper, it seemed like the obvious answer to me, but on this one my logic was alien to everyone else.

So I scanned the paper, documented all my functions, and laid out all the needed input formating, and wrote an additional document about how the application was supposed to accomplish its tasks. I quit more that job more than 3 years, and I still talk about that software when they need something specific (most recently 6 months ago). It was less than a Kloc (1000 Lines Of Code) but it was still sophisticated enough to warrant questions 2 and half years later.

Answer 14

b) Document everything that isn't obvious, or when in doubt. In this case:

/** Copies all readable bytes from inStream to outStream. outStream will be flushed, 
 *  but neither stream will be closed.
 */

You have already written that inStream is an InputStream, and you don't have to specify that it's intended to read bytes in its own comment, as you already do so in the function's comment

Answer 15

Only document those methods that you want people to be able to use, and use effectively.