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. 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
