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
