On Mon, Jul 25, 2011 at 10:27 AM, Torsten Curdt <tcu...@vafer.org> wrote:
>>> 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.
>
> With the "state of mind" I mean: think like the user and what matters to him.
> So I am mostly with you - you just haven't have realized that ;)
>
> No one is saying that describing an API is useless. In fact I am
> saying the exact opposite. I just question the idea of describing
> every method being useful. When you say that the following javadocs
> are useful - then there is probably not much left to discuss anyway:
I understood where you are coming from, Torsten, hence my
pseudo-suggestion (pseudo- in that I don't personally have time to do
it) that we use some custom mechanisms for the best of both worlds.
As I see it, using checkstyle, etc., to require that Javadoc is in
place (and I really agree that documentation requirements should focus
on non-private members) is our best available means of verifying that
we have attempted to provide adequate documentation. For me, using
@inheritDoc (without elaboration) is a way to say "I have evaluated
this method, and I believe that it does nothing remarkable beyond what
might be expected of the given subclass in the context of the defined
operation." A custom doclet might for example accomplish the same
thing using a custom annotation, eliminating the wrapping javadoc
comment. Opinions will vary as to whether this very slight savings in
code size would justify the work of implementing it, but this is only
an example of certain conventions upon which we might agree so that
our javadoc is as complete as it needs to be, while our code is
allowed to be as clean as it can be. Our API documentation isn't
perfect just because javadocs are required, but it's probably better
than it would be if they weren't.
Matt
>
> /** Serial */
> private static final long serialVersionUID = 1234L;
>
> /** The Foo's user id. */
> private int userId;
>
> /**
> * Constructor
> */
> public Foo () {
>
> /**
> * Get this Foo's name.
> *
> * @return This Foo's name.
> */
> public String getName() {
>
> /**
> * Set this Foo's name.
> *
> * @param name This Foo's new name.
> */
> public void setName(String name) {
>
> cheers,
> Torsten
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
> For additional commands, e-mail: dev-h...@commons.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org
