Maybe send around some examples of places where you think it would have been helpful.
On Aug 22, 2007, at 10:32 AM, Jason Voegele wrote: > On Wednesday 22 August 2007 1:21, Orion Letizi wrote: >> 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. > > I can understand this point of view. However, I think that some > amount of > Javadoc documentation would be beneficial in at least the following: > > 1) Public APIs (as already mentioned by Geert) > 2) Interfaces - they are supposed to be contracts after all and > since Java > lacks Design By Contract as a language feature, something needs to > spell out > the semantics of the contract > 3) Methods that are designed to be overriden by subclasses > > As for complicated/tricky code, I think that is best handled by > refactoring > (if possible) or including a non-Javadoc comment describing > implementation > details. > > -- > Jason Voegele > All language designers are arrogant. Goes with the territory... :-) > -- Larry Wall in <[EMAIL PROTECTED] > _______________________________________________ > 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
