Vincent Siveton wrote:
Hi,
2008/7/5, Benjamin Bentmann <[EMAIL PROTECTED]>:
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?
I discourage the use of generated javadoc for getter/setter (not
really useful). If some getter make some internal things, the javadoc
is required.
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.
Pre/post conditions are importants things IMHO, like could be null,
could return null etc.
Just wondering what is more expensive or time consuming: Adding proper
documentation right from the start or fixing potential API misuses
afterwards?
Totally agree with you (concept of done in the agile way ;) )
The main question is:
Does the team want to refute any commits without proper javadoc?
I don't think we should reject commits that lack proper javadoc. Just let the
committer know where docs should be improved or document it yourself if you
notice something missing.
Cheers,
Vincent
Benjamin
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
