Re: unchecked conversion warning.
On 6/1/2012 2:14 AM, Robert Klemme wrote:
On 31.05.2012 22:50, Eric Sosman wrote:
[...]
(JavaDoc is both a blessing and a curse: It's a blessing in that
developers *are* encouraged to write documentation, and it's a curse
in that *developers* are encouraged to write documentation. ;)
In what ways is that a curse? I would actually say that the weight
totally falls on the blessing side because JavaDoc together with modern
IDE makes the threshold so low to write documentation that there really
is not much of an excuse left to not do it. And documentation is important.
First, don't overlook the smiley.
My point is simply that the people who write code are trained in
writing code, not necessarily in writing documentation. Meanwhile,
the people who are good at expository technical prose are quite often
not empowered to change the code. Result: You nearly always get
documentation (that's the blessing), but the quality thereof is a
crap-shoot (the curse).
As an example of what I consider unhelpful documentation, take
a look at java.io.PipedInputStream. We are told
"A pipe is said to be /broken/ if a thread that was
providing data bytes to the connected piped output
stream is no longer alive."
Does this make sense? Does it imply that a PipedOutputStream is
writable by one and only one Thread? Which Thread? Or, if it's
writable by many Threads, does it mean that the PipedInputStream
gets "broken" as soon as any one of those threads exits, even if
the others are still alive and writing? What, exactly, *does*
this statement mean? To me, it means "Use the Source, Luke" --
Which is where I'd have been were there no JavaDoc at all.
Finally, don't overlook the smiley.
--
Eric Sosman
esosman@ieee-dot-org.invalid