On 7/25/11 6:31 AM, Matt Benson wrote: > On Mon, Jul 25, 2011 at 5:07 AM, Torsten Curdt <tcu...@vafer.org> wrote: >>>> Good code needs little javadocs. >>> I disagree strongly. >>> >>> The Javadoc should present the public API (and should ideally be >>> written before the code - i.e. the code implements the docs). >>> >>> If the only documentation is the code, it is much harder for users to >>> determine how to use the API. > I have to agree. Ever programmed against cglib? When depending on > libraries with no javadoc, I invariably find myself going to the code, > which I really shouldn't have to do. Of course, I must admit that > even for libraries that appear to be reasonably well-documented (e.g. > Spring), I still often end up going to the code. > >>> For some code (interfaces, abstract methods) only Javadoc is available. >> Did you even bother to read the blog post? > I read it, Torsten. What I get from its main theme though is that you > are encouraging the class-level "book" comment one sees in e.g. > oac.jxpath.JXPathContext or Mockito's main Mockito class. I suppose > that's a matter of preference, but personally I prefer to digest an > API in smaller bits than that.
Honestly, I think its best to have both. Good class-level javadoc describes the overall function of the class, primary properties and use cases and macro-level considerations about what the class expects from or how it interacts with its execution environment. Method level javadoc specifies contracts. If you have to skimp on one of these, for library code it is in general better to focus on the method-level documentation, because that is what the user always sees and depends on and also what can be validated by the unit tests. Phil > > Matt > >> --------------------------------------------------------------------- >> To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org >> For additional commands, e-mail: dev-h...@commons.apache.org >> >> > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > For additional commands, e-mail: dev-h...@commons.apache.org > > --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
