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? 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]
