Should all public methods of an API be documented?
- by cynicalman
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)...
