+1
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
