On Tue, Jan 11, 2011 at 10:15 AM, Gilles Sadowski <gil...@harfang.homelinux.org> wrote: > Hi. > > Is there a document presenting best practices for writing code for CM? > Right now I'm thinking about the recent overwrites of Javadoc comments; so I > think that it could be useful to lay out what should be there (beyond the > obvious that "everything should be documented").
Yes. See http://commons.apache.org/math/developers.html. > > A few things that come to mind: > > * All exceptions that could be thrown must be documented in a "@throws" tag, > indicating all the possible causes of the exception (such as the > assumed preconditions) +1 - tricky to do in all cases since we have abandoned checked exceptions and unchecked exceptions can propagate unexpectedly through API layers. I do agree with the spirit of this, though and would say *must* for exceptions that may immediately be thrown as a result of precondition violation. This follows from the principles laid out in the Developer's Guide. > > * The "@param" tag should not contain redundant information (such as > preconditions since they must be documented in a "@throws" tag). For the rest of this, I would prefer that we stick with our previously agreed convention (stated in the doc above) to just follow the Sun conventions. It will be much easier for contributors and those applying patches if we just follow the standard conventions. A couple of areas where we have slipped a bit over the years that I would rather apply energy to than formatting are the following (from the Developers' guide): # All component contracts must be fully specified in the javadoc class, interface or method comments, including specification of acceptable ranges of values, exceptions or special return values. # External references or full statements of definitions for all mathematical terms used in component documentation must be provided. # Implementations should use standard algorithms and references or full descriptions of all algorithms should be provided. # Additions and enhancements should include updates to the User Guide. I have an open action, for example, to define precisely what we mean by "support" for distributions. What is important to me is the content of the javadoc, not so much what elements include what info. I think, for example, http://s.apache.org/S39 is fine. In some cases, the preconditions of a method involve multiple parameters or other context info so it is more convenient to state them in the main method description. Again, the important thing is to clearly state (or reference) a) relevant mathematical definitions and algorithms b) preconditions and c) exceptions or NaN returns when preconditions are not met. Phil --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
