commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Torsten Curdt <tcu...@vafer.org>
Subject Re: [math] Inherits doc and @Override
Date Mon, 25 Jul 2011 15:27:18 GMT
>> 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:

    /** 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-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org


Mime
View raw message