On Sun, Jun 21, 2009 at 6:57 PM, Michael Jakl <[email protected]>wrote:
> Hi! > > On Sun, Jun 21, 2009 at 23:04, Emmanuel Lecharny<[email protected]> > 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. > Very good point for identifying the code to document best based on a 80/20-like principal to documentation. I really like this idea Michael! Alex -- Alex Karasulu My Blog :: http://www.jroller.com/akarasulu/ Apache Directory Server :: http://directory.apache.org Apache MINA :: http://mina.apache.org
