Prev: logging into site using form validation http components
Next: Windows priorities with runtime.exec
From: markspace on 6 Jun 2010 11:08
Patricia Shanahan wrote:
> However, I think interface documentation often needs
> explanation of the interface's intended use. Those comments are not
> superfluous - they are a proper part of the documentation, but not
> contract.
>


I agree with Patricia's excellent observation and example, and would
like to add one more:

Sometimes, programmers make mistakes. By adding "superfluous" comments
to the Javadoc text, you create a sort of redundancy in the contract.
Another programmer then can determine if your contract really does
fulfill your intended use, or if you made an error in writing the contract.

A comment that specifies only what the code does is itself of limited
use. If you want to know that, read the code. The intended use, a sort
of gloss regarding the design, is often more valuable in the long run.
At least, in my experience.
From: Patricia Shanahan on 6 Jun 2010 12:15
markspace wrote:
....
> A comment that specifies only what the code does is itself of limited
> use. If you want to know that, read the code. The intended use, a sort
> of gloss regarding the design, is often more valuable in the long run.
> At least, in my experience.

I disagree with this relative to Javadoc comments. It is very, very
important to be able to tell what a method call will do without reading
its implementation.

I have sometimes had to dig down through about 6 layers, reading
implementations, in order to find out whether a function in the top
layer is supposed to be able to return null or not. I didn't care about
any of those methods, just whether the caller of the top level function
needed to deal with null.

Patricia
From: Eric Sosman on 6 Jun 2010 15:03
On 6/6/2010 2:25 PM, Stefan Ram wrote:
> Patricia Shanahan<pats(a)acm.org> writes:
>> I disagree with this relative to Javadoc comments. It is very, very
>> important to be able to tell what a method call will do without reading
>> its implementation.
> [...]
> (In my question, I was referring to documentation of /interfaces/,
> thus of, /abstract/ methods, which anyways do not need to have any
> implementation at all.)

Yes, but the contract of the method should state whether it
can return null and under what conditions, unless it's "obvious."
For example, consider the remove() and poll() methods of the Queue
interface: the contract for poll() says that it returns null if its
queue is empty, while that for remove() says NoSuchElementException
is thrown. These are not descriptions of particular implementations
that just happen to behave this way, but statements about how *all*
implementations are supposed to behave. The Queue interface, even
though it has no implementation of its own to describe, nonetheless
describes its implementations.

--
Eric Sosman
esosman(a)ieee-dot-org.invalid
From: Lew on 6 Jun 2010 15:51
Eric Sosman wrote:
> Yes, but the contract of the method should state whether it
> can return null and under what conditions, unless it's "obvious."
> For example, consider the remove() and poll() methods of the Queue
> interface: the contract for poll() says that it returns null if its
> queue is empty, while that for remove() says NoSuchElementException
> is thrown. These are not descriptions of particular implementations
> that just happen to behave this way, but statements about how *all*
> implementations are supposed to behave. The Queue interface, even
> though it has no implementation of its own to describe, nonetheless
> describes its implementations.

That's an excellent example, but I just want to quibble over terms.
Specifying that one returns 'null' when empty and the other throws
'NoSuchElementException' when empty does not describe implementation, it
describes behavior that implementations will realize. The fact that this
behavior cannot be described in a compiler-enforced manner does not make it
implementation any more than that each method returns an instance of type 'E'
(when the queue is not empty).

Describing what the method returns is a matter of contract, not
implementation. It happens that Java cannot always completely describe a
contract in a compiler-enforced manner. That does lead to potential bugs,
e.g., that a custom Queue implementation of 'remove()' will not throw
'NoSuchElementException' when empty, while preventing others, e.g., that
'remove()' might return a different type of instance than 'E'. It's not a
question of the first being implementation and the second contract; both are
contract matters, the first unenforced by the compiler, the second enforced.

--
Lew
From: Arne Vajhøj on 6 Jun 2010 17:52
On 06-06-2010 12:15, Patricia Shanahan wrote:
> markspace wrote:
> ...
>> A comment that specifies only what the code does is itself of limited
>> use. If you want to know that, read the code. The intended use, a sort
>> of gloss regarding the design, is often more valuable in the long run.
>> At least, in my experience.
>
> I disagree with this relative to Javadoc comments. It is very, very
> important to be able to tell what a method call will do without reading
> its implementation.
>
> I have sometimes had to dig down through about 6 layers, reading
> implementations, in order to find out whether a function in the top
> layer is supposed to be able to return null or not. I didn't care about
> any of those methods, just whether the caller of the top level function
> needed to deal with null.

Yep.

The java docs should explain *what* the code does and
looking at the code is necessary to see *how* the code
does it.

Arne

First  |  Prev  |  Next  |  Last
Pages: 1 2 3
Prev: logging into site using form validation http components
Next: Windows priorities with runtime.exec