Vincent Siveton wrote:
http://svn.apache.org/repos/asf/maven/site/trunk/src/site/apt/developers/conventions
code.apt
* <<Documentation>>: Document public interfaces well, i.e. all
non-trivial public and protected functions should include Javadoc that
indicates what it does.
I would like to point out there are almost no methods that are really
non-trivial. In particular, getters and setters are not trivial.
Take for instance getComponents() from the Plexus'
ComponentSetDescriptor. This method returns a null collection if no
components have been added to the list yet. The javadoc doesn't tell
this "triviality" that can easily cause NPEs in client code
(MPLUGIN-114, MNG-2087). BTW, new ComponentSetDescriptor().toString()
also dies with a NPE.
Concerning collections, other "trivial" aspects are whether to return
writable/unmodifiable live views or snapshots. For input parameters,
will a setter like setComponents() make a copy of the input collection
or will later changes to the supplied collection by the caller affect
the ComponentSetDescriptor?
Being open-source appears to support the habbit of omitting
documentation about member invariants and method pre-/postconditions.
This in turn leaves clients with the only choice of evaluating the
current implementation to derive the behavior. Then, nobody can tell
what aspect of the behavior is considered part of the API and what is
just implementation-specific/buggy.
Just wondering what is more expensive or time consuming: Adding proper
documentation right from the start or fixing potential API misuses
afterwards?
Benjamin
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
