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
