On 7/25/11 8:27 AM, Torsten Curdt 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 ;)
I get your point. The problem that I have never been able to solve,
though, is where to draw the line. My HO is that as soon as you
open the door to people saying "obvious" and omitting method
javadoc, things devolve rather quickly. This is especially true
when it comes to "self-documenting" method names. The examples
below certainly look innocuous at first. But what happens when one
of the setters is changed to have a side effect? Or when new
constraints are placed on the property? And where, other than the
getter, do you document what the property means? I guess when
things become nontrivial, you decide it is no longer "obvious" and
add javadoc. Again, having been burned by seemingly "obvious" code
many times (including a long and painful experience deciphering
earlier versions of [pool] and [dbcp] that had terrible javadoc), my
admittedly conservative tendency is to want to create the right
documentation structure at the beginning rather than having to keep
track of when things become no longer "obvious."
Phil
>
> 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-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
