Hi! On Sun, Jun 21, 2009 at 23:04, Emmanuel Lecharny<elecha...@apache.org> wrote: >> I have to admit that this kind of quantitive analysis doesn't tell me >> much. I'd rather improve the javadoc for a central class than write a >> new one for a simple interface setter method where the name and >> parameters speak for themselves. >> > [...] > > I don't like over documented code, for instance (I mean, comments *inside* > the code). Just because if you needed to add some comments in your code, > that means your code is probably too complex to be understood by a normal > human being (ie , the 'average programmer' ;), and you may have to split the > code a bit. The very same applies for naming. Not being english native > speakers make it difficult to use the exact correct name for a field or a > function.
The documentation I found in Vysper proved very helpful and - of course - more of it would do good. Anyway I'd second the view that good documentation shouldn't repeat what the code says best. The HTML argument is a good one, but IMHO more relevant in closed source projects, instead of a RTFM we have the option for a RTFC(ode). >> >> But if you point out critical code that misses a javadoc, unit test or >> spec compliance annotation or code comment, you'll never find me >> disagreeing with you. (I reserve the right to ask for a patch, though. ;-) >> > > As a general politic, I think that the one who write the code at first is > the one who *knows*. Hopefully, modern IDE generates all this boring Javadoc > for setters and getters. Otherwise, I don't think that adding headers for > private method is always mandatory (sometime it helps). It's all about how > easy it is to understand what a method do. However, what seems easy for you > might be a bit more complicated for someone just diving into your code. > > I personally find it polite to add headers and javadoc, it makes the code > more welcoming. Like names for the street and number on the doors. >> >> So my question is, where is that code which most deserves being improved >> in this way? >> > > Well, without having done the quality analysis yet, my answer, not a > surprise, will be : all the interface and public methods without Javadoc ;) > Very PC, I know ... > > But as this is not the answer you are expecting, so give me a couple of > week, if I can find the time to dive into the code. I think Emmanuel touched the essence of the discussion a few paragraphs earlier: "the one who wrote the code knows what to document". So not surprising I'm adding "Javadoc for PubSub-related classes" to my todo list :) Maybe a quick dependency graph could show us the "hotspots" which are the classes many others use/depend on - these are the ones which need good documentation, I'd guess. Cheers, Michael PS: If the code and the comments disagree, then both are probably wrong. -- Norm Schryer
