final methods and classes

[Lew]

Try Google on:
jdbc timestamp
and see what show up first.

How will the popularity of old information change the fact that he linked to
out-of-date documents?

By linking to current documents,
<http://java.sun.com/javase/6/docs/api/java/sql/Timestamp.html>
even for classes that existed in earlier versions, one leads the querent to
better hotlinks, enhanced explanations, new interfaces implemented, generics
type parameters, and different packages and types listed in the various
frames. You deprive the querent of that enhanced hyper-navigation opportunity
or other potentially helpful information by steering them to out-of-date docs.

All your suggestion does is provide evidence that over a longer period of
time, older docs have had more time to gain ranking in a Google search. It
completely ignores the reduction in helpfulness that an obsolete link provides.

 

[Wojtek]

Lew wrote :

How will the popularity of old information change the fact that he linked to
out-of-date documents?

By linking to current documents,
<http://java.sun.com/javase/6/docs/api/java/sql/Timestamp.html>
even for classes that existed in earlier versions, one leads the querent to
better hotlinks, enhanced explanations, new interfaces implemented, generics
type parameters, and different packages and types listed in the various
frames. You deprive the querent of that enhanced hyper-navigation
opportunity or other potentially helpful information by steering them to
out-of-date docs.

All your suggestion does is provide evidence that over a longer period of
time, older docs have had more time to gain ranking in a Google search. It
completely ignores the reduction in helpfulness that an obsolete link
provides.

So why then does Sun keep out of date docs around?


I don't disagree with you, like Arne said it was the first link, and I
should have found a link which is up to date.

 

[Marcin Rze¼nicki]

Lew wrote :









So why then does Sun keep out of date docs around?

Because people are still using older JDKs

 

[John B. Matthews]

How will the popularity of old information change the fact that he
linked to out-of-date documents?

By linking to current documents,
<http://java.sun.com/javase/6/docs/api/java/sql/Timestamp.html>
even for classes that existed in earlier versions, one leads the
querent to better hotlinks, enhanced explanations, new interfaces
implemented, generics type parameters, and different packages and
types listed in the various frames. You deprive the querent of
that enhanced hyper-navigation opportunity or other potentially
helpful information by steering them to out-of-date docs.

All your suggestion does is provide evidence that over a longer
period of time, older docs have had more time to gain ranking in a
Google search. It completely ignores the reduction in helpfulness
that an obsolete link provides.

So why then does Sun keep out of date docs around?[/QUOTE]

I've wondered about this. An undecorated search often turns up 1.4.2
links. Version 1.4.2 happens to be the latest, widely-used version that
is not getting periodic updates. When later versions are updated, it
seems to take a while for the new pages to "climb" back into the top
ranking.

I don't disagree with you, like Arne said it was the first link, and
I should have found a link which is up to date.

Although IDEs typically summon the relevant document, I've then posted a
careless "file://" link or two. Using Google, I've found that adding a 5
or 6 anywhere in the query helps.

 

[Arne Vajhøj]

How will the popularity of old information change the fact that he
linked to out-of-date documents?

It does not.

But you asked about WHY.

And I supplied a possible explanation.

Arne

 

[Arne Vajhøj]

Perhaps google is not the definitive answer to java docs, then.

Google is not perfect.

But it may still be the best around.

Arne

 

[Arne Vajhøj]

Lew wrote :

So why then does Sun keep out of date docs around?

I don't disagree with you, like Arne said it was the first link, and I
should have found a link which is up to date.

Not everyone is using 1.6. A lot is still on 1.5 and 1.4.2. A few
is still on 1.3.1 and 1.2.2.

It is a good service that the old docs is available. Given how slow
Java upgrades happen especially in the Java EE space, then I would
say that it is a must to have the old docs around.

But what SUN could do was to in the online version (not in the
offline downloadable version) provide a little header with links
to the same class in other Java versions, so it was very easy to
click on the "Java 6" link and get the latest version.

(idea stolen from Microsoft .NET)

Arne

 

[Arne Vajhøj]

Wojtek wrote:
http://java.sun.com/j2se/1.4.2/docs/api/java/sql/Timestamp.html which
extends Date.
Lew wrote:
Out of curiosity, why are you linking to out-of-date Javadocs?
Arne Vajhøj wrote:
Try Google on:
jdbc timestamp
and see what show up first.
How will the popularity of old information change the fact that he
linked to out-of-date documents?

By linking to current documents,
<http://java.sun.com/javase/6/docs/api/java/sql/Timestamp.html>
even for classes that existed in earlier versions, one leads the
querent to better hotlinks, enhanced explanations, new interfaces
implemented, generics type parameters, and different packages and
types listed in the various frames. You deprive the querent of
that enhanced hyper-navigation opportunity or other potentially
helpful information by steering them to out-of-date docs.

All your suggestion does is provide evidence that over a longer
period of time, older docs have had more time to gain ranking in a
Google search. It completely ignores the reduction in helpfulness
that an obsolete link provides.

So why then does Sun keep out of date docs around?

I've wondered about this. An undecorated search often turns up 1.4.2
links. Version 1.4.2 happens to be the latest, widely-used version that
is not getting periodic updates. When later versions are updated, it
seems to take a while for the new pages to "climb" back into the top
ranking.

I don't disagree with you, like Arne said it was the first link, and
I should have found a link which is up to date.

Although IDEs typically summon the relevant document, I've then posted a
careless "file://" link or two. Using Google, I've found that adding a 5
or 6 anywhere in the query helps.[/QUOTE]

That is what I use also. If I remember it.

Arne

 

[Mike Schilling]

But what SUN could do was to in the online version (not in the
offline downloadable version) provide a little header with links
to the same class in other Java versions, so it was very easy to
click on the "Java 6" link and get the latest version.

(idea stolen from Microsoft .NET)

That is the *one* way in which the online .NET docs improve on oinline
javadoc.

Well, that and having more code examples.

 

[Arved Sandstrom]

That is the *one* way in which the online .NET docs improve on oinline
javadoc.

Yeah. Oracle does it too, on many pages - if you end up on an 11g page
they'll usually have a convenient link for the 10g version of the same
thing (if it exists.)

Well, that and having more code examples.

+1.

AHS

 

[Wojtek]

Mike Schilling wrote :

That is the *one* way in which the online .NET docs improve on oinline
javadoc.

Well, that and having more code examples.

The PHP site also allows user comments. These are usually code sni[ets,
tips and tricks, gotchas, and so on.

You need a ui/pw so spam is at a minimum.

 

[Arne Vajhøj]

And even if so, why do you (Leif, Mike, etc) feel obliged to prevent him
from shooting his toes off?

Not commenting on the specific context, but in general:

If the company culture is "it does not matter if the project fail
if you can prove it was not your fault", then there is no reason.

But if the company culture is "the important thing is that the
team/company succeed", then there is a reason.

Arne

 

[Arne Vajhøj]

That's deceptive to think that API is "clearer" because of extensive
use of finals, and if you believe that your work is less/more 'shoddy'
because of finals, you are lying to yourself.

I agree.

The "I really think language XYZ is better than language ABC, so when
I code in ABC I try to make to code work like XYZ" line of thought
usually just creates weird code.

Arne

 

[Andreas Leitgeb]

If the company culture is "it does not matter if the project fail
if you can prove it was not your fault", then there is no reason.

If you and the user of the API work on the same project, then I'd expect
other channels of communication to be available, where the user could complain
to you about an (in his eyes) wrong "final". You'd then discuss the matter
and in the end either remove the final, or find a better way to solve the
user's (actually colleague's) problem.

Adding "final", where no discussion about it is possible, is like:
"I know better - if you disagree, then you're ly^H^Hwrong."
Some "final"s even *are* right, but for the *idly* added ones, chances
are obviously less than 100% of being right.