JavaDocs in the other direction

J

Joona I Palaste

JavaDocs, as we know them, describe what a method does, to help people
who are calling it from outside code.
But what if we need documentation in the other direction - to help
people who are trying to implement the method? They may need
documentation about when and where the method is going to get called,
and with what parameters, and how its return value will be used.
In short, what the method expects, and what it assures.
For example, this sort of "JavaDoc" might be necessary:

/**
* Should create a shallow clone of the array.
* @param arr: This is the array. It will already have been sorted
* according to the natural order, so don't worry about using
* optimised algorithms. Also, all references will be non-null.
* @return Another array. This array is a shallow copy of the
* original. No one is ever going to modify this array, but the
* original might get modified. Think of this as a "backup array" to
* see what the original array "originally" looked like.
*/
public Comparable[] cloneArray(Comparable[] arr);

Are there such JavaDocs defined? Does anyone use them? Would there be
any real benefit from them?
 
M

Michael Borgwardt

Joona said:
JavaDocs, as we know them, describe what a method does, to help people
who are calling it from outside code.
But what if we need documentation in the other direction - to help
people who are trying to implement the method? They may need
documentation about when and where the method is going to get called,
and with what parameters, and how its return value will be used.

I don't see the difference. The information in the comment you give as an
example is *at least* as important to the users of the API as to the
implementor. The only difference is in the wording: to the implementor
the parameter array "will already have been sorted", to the caller
it *must* be sorted before calling the method.
 
D

David Robbins

Joona I Palaste said:
JavaDocs, as we know them, describe what a method does, to help people
who are calling it from outside code.
But what if we need documentation in the other direction - to help
people who are trying to implement the method? They may need
documentation about when and where the method is going to get called,
and with what parameters, and how its return value will be used.
In short, what the method expects, and what it assures.
For example, this sort of "JavaDoc" might be necessary:

/**
* Should create a shallow clone of the array.
* @param arr: This is the array. It will already have been sorted
* according to the natural order, so don't worry about using
* optimised algorithms. Also, all references will be non-null.
* @return Another array. This array is a shallow copy of the
* original. No one is ever going to modify this array, but the
* original might get modified. Think of this as a "backup array" to
* see what the original array "originally" looked like.
*/
public Comparable[] cloneArray(Comparable[] arr);

Are there such JavaDocs defined? Does anyone use them? Would there be
any real benefit from them?

well, when writing code it is a common practice to create pseudo code from
the requirements or design documentation when you start actual coding. if
you are thinking ahead you format comments so that tools like javadoc can
extract them and create the actual software design documentation for review
before implementation. this saves having to write a separate document
before starting on roughing in the code. if you are really doing it the
smart way the pseudo code is compilable and can be used to check
compatibility of interfaces before finishing the design. there are lots of
books and tools available that talk about the software design process and
how to automate it to speed development and reduce errors.
 
A

Adam Jenkins

Joona said:
JavaDocs, as we know them, describe what a method does, to help people
who are calling it from outside code.
But what if we need documentation in the other direction - to help
people who are trying to implement the method? They may need
documentation about when and where the method is going to get called,
and with what parameters, and how its return value will be used.
In short, what the method expects, and what it assures. ....
Are there such JavaDocs defined? Does anyone use them? Would there be
any real benefit from them?

Sure, look at the documentation for any interface. The Javadocs for the
standard Java libraries are full of examples. For example, look at the
documentation for java.util.{Collection,Map,List}. They're exactly the
kind of documentation you're talking about. They define how
implementations of these interfaces are expected to behave. Some more
examples from the standard libraries:

- org.w3c.dom.*
- org.xml.sax.*
- most of java.sql.*

I'm not sure what you think is different about these from the example
you're giving.
 

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Members online

Forum statistics

Threads
473,744
Messages
2,569,484
Members
44,903
Latest member
orderPeak8CBDGummies

Latest Threads

Top