commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Phil Steitz <>
Subject Re: [math] Inherits doc and @Override
Date Mon, 25 Jul 2011 15:06:56 GMT
On 7/25/11 6:55 AM, Torsten Curdt wrote:
> I am not saying don't use javadocs. It's all about using javadocs effectively.
> Forcing javadocs on all methods leads to bloat and noise. Better
> present stellar javadocs on public APIs and document how the library
> works. Having great examples helps a great deal ...but don't (please
> don't!) use Eclipse to auto-complete javadocs or have useless javadocs
> on setters/getters. Instead think when you write.
> How much is obvious from the method signature already? What is not?
> Not sure there is a checkstyle rule for that.
> Maybe I am working too much in other languages to appreciate the "less
> is more" way of coding.
> Self descriptive code is less a myth but more a state of mind when
> writing that code and documentation.

The problem with that "state of mind" is that unless and until you
clearly specify a contract for your code (and write tests to
validate it) you - and your users - don't really know what it does. 
That may be fun and fine for small bits of code or even whole
applications developed by a small, close-nit team.  It fails
miserably when others start depending on it or when the
implementation or execution environment of the code changes.  Having
to try to reverse engineer the thought process of a developer whose
excellent idea is described only "in beautiful, self-describing
code" is no fun, especially when that code has failed or delivered
unexpected results.  Please lets no go there in Commons.

> Anyway ...I'll shut up now :)
> ---------------------------------------------------------------------
> To unsubscribe, e-mail:
> For additional commands, e-mail:

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message