Someone mentioned that their is a diff between javadoc and comments. I think that is an important point. Having comments on important stuff in methods and class comments should be a no brainer. Whether they are actual java docs with all their verbosity is a separate question.
Here is a brief list of who to bug about each of these topics if you want to do some doc work on them. We have some limited docs on some of these on the wiki but more would be great! > - Config modules pester juris, eugene, geert, to learn about these > - Monkeys (actually, there are some good docs out there that have > been helpful on this) Jason, hung > - Session transparency Tim, you :-) > - Caching and coherency Not sure exactly which part you mean by this > - Locking Antonio, saravanan me > > - Transactions antonio saravanan me > - Persistence / the database EY, saravanan, me > - Memory management Tim, saro, me > - Boot jars Juris, gary k, me Cheers, Steve On Aug 22, 2007, at 10:54 AM, Alex Miller wrote: > I don't buy this argument. > > 1) It's not really that much work, especially when you amortize > over the cost (which will only grow over time) of the writer or > others understanding it later. > 2) See #1 (really, it's not that hard to keep in sync) > 3) I agree in principle, but ultimately some stuff is irreducibly > complicated. That makes it doubly important to document. > > I've worked in big code bases (MetaMatrix was in the 600K actual > LOC range) and over a multi-year period I feel that doing a > reasonable amount of javadoc was worth the effort. On a scale of > 0-10 of javadocness, I'm comfortable in the 4-6 range on average > and 9-10 for public-facing. My impression so far is that > Terracotta is down around 1. I'm not dogmatic about this or > anything and I don't think we should go on some grand javadoc > rampage. But as you're working on a bug in some code, if you have > to "figure something out" about how it works, I think it would be a > great thing to drop a comment. As always, comments that explain > "why" are generally far more valuable than those about "how" unless > "how" involves deep magic. > > You could convince me a little more if you could say "the way this > all works is clearly spelled out in these design docs", but those > seem to be woefully missing as well. I understand how this > happens; I've been there myself. But I think with coming growth, > tc is approaching an inflection point where an influx of newbies > (like me :) will mean that not having this documentation will slow > things down by tying up both the experienced and the newbies in > repeatedly passing down the oral history of the code. > > So, regarding the design stuff, I have a proposal: if you help me > understand something in depth, I'll write it down for you! > > Here's a starter list of topics I'm interested in: > - Config modules > - Monkeys (actually, there are some good docs out there that have > been helpful on this) > - Session transparency > - Caching and coherency > - Locking > - Transactions > - Persistence / the database > - Memory management > - Boot jars > > Your faithful scribe, > Alex > > > ----- Original Message ----- > From: "Orion Letizi" <[EMAIL PROTECTED]> > To: "Geert Bevin" <[EMAIL PROTECTED]> > Cc: "Alex Miller" <[EMAIL PROTECTED]>, "Jason Voegele" > <[EMAIL PROTECTED]>, [email protected] > Sent: Wednesday, August 22, 2007 12:21:05 PM (GMT-0600) America/ > Chicago > Subject: Re: [Eng] Javadoc policy > > I'm in agreement with Geert. Three points that sway me against using > javadoc: > > 1) It's a lot of work > 2) It's easy for the code to drift from the docs-- which is worse > than no docs at all. > 3) If it's really complicated and hard to understand, maybe there's > something wrong with it. I'm not a fan of fixing stuff in > documentation. > > I am in favor of writing stuff up in the wiki about how to approach > the code, though. Maybe an outline of what the major packages are > for and how the code is organized. It's still subject to doc drift, > but there's no implicit expectation that the docs line up with actual > code. > > --Orion > > On Aug 22, 2007, at 10:14 AM, Geert Bevin wrote: > >> I have to admit that I made the same impression when I started to >> look at the code. Then I started to realize that there's so much >> interaction in DSO that there would be a lot to javadoc. The IDE's >> inspection features are the best documentation for the interaction of >> the internals imho. In general, when it's not a public user API, I'm >> much more in favor of documenting inside the code when non trivial >> logic is written than to add javadoc to methods that well never be >> used outside of the company. Maintaining javadoc is a tricky task and >> all too often developers forget to update the documentation as >> features and behavior changes. >> >> On 22 Aug 2007, at 17:25, Alex Miller wrote: >> >>> As a new "user" of the code, I'd say that in general the code could >>> definitely benefit from some comments. There is a lot of tricky >>> stuff here that a sentence or two would help with a lot. >>> >>> I'm not a big fan of "you must write javadoc for every method", >>> more somewhere in the middle. I think as Jason mentioned, >>> documenting public stuff is generally a good idea. I don't see any >>> point in documenting getter/setters or other obvious stuff, but I >>> think we're far from that being a problem. :) >>> >>> >>> >>> >>> ----- Original Message ----- >>> From: "Steven Harris" <[EMAIL PROTECTED]> >>> To: "Jason Voegele" <[EMAIL PROTECTED]> >>> Cc: "TC Engineering" <[EMAIL PROTECTED]> >>> Sent: Wednesday, August 22, 2007 9:47:46 AM (GMT-0600) America/ >>> Chicago >>> Subject: Re: [Eng] Javadoc policy >>> >>> No rules against it. Some of us feel that the extra lines of stuff >>> makes code harder to read and >>> only do it when we feel a method is confusing or will be >>> available to >>> people outside terracotta >>> but if you like them and find them useful then do it. I think their >>> is room on this topic for reasonable >>> people to disagree. >>> >>> Cheers, >>> Steve >>> >>> On Aug 22, 2007, at 6:17 AM, Jason Voegele wrote: >>> >>>> I tend to write Javadoc comments for all public and protected >>>> methods, and >>>> oftentimes even for private methods in anticipation of the fact >>>> that they may >>>> some day be refactored into public methods of a utility class. >>>> However, I've >>>> noticed that most of the Terracotta code base lacks these comments >>>> even for >>>> public methods and classes. I'm wondering if this is a policy >>>> decision, or >>>> if this is something left to the whims of the individual >>>> developer? In other >>>> words, if I liberally Javadoc my code, will I have my knuckles >>>> slapped with a >>>> ruler, or will I merely be thought of as an eccentric Kentuckian? >>>> >>>> -- >>>> Jason Voegele >>>> Man must shape his tools lest they shape him. >>>> -- Arthur R. Miller >>>> _______________________________________________ >>>> Eng mailing list >>>> [EMAIL PROTECTED] >>>> http://mail.terracottatech.com/mailman/listinfo/eng >>> >>> _______________________________________________ >>> Eng mailing list >>> [EMAIL PROTECTED] >>> http://mail.terracottatech.com/mailman/listinfo/eng >>> >>> _______________________________________________ >>> Eng mailing list >>> [EMAIL PROTECTED] >>> http://mail.terracottatech.com/mailman/listinfo/eng >> >> -- >> Geert Bevin >> Terracotta - http://www.terracotta.org >> Uwyn "Use what you need" - http://uwyn.com >> RIFE Java application framework - http://rifers.org >> Music and words - http://gbevin.com >> >> _______________________________________________ >> Eng mailing list >> [EMAIL PROTECTED] >> http://mail.terracottatech.com/mailman/listinfo/eng > > > _______________________________________________ > tc-dev mailing list > [email protected] > http://lists.terracotta.org/mailman/listinfo/tc-dev _______________________________________________ tc-dev mailing list [email protected] http://lists.terracotta.org/mailman/listinfo/tc-dev
