Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]
Groups > comp.lang.java.programmer > #14976
| From | Eric Sosman <esosman@ieee-dot-org.invalid> |
|---|---|
| Newsgroups | comp.lang.java.programmer |
| Subject | Re: unchecked conversion warning. |
| Date | 2012-06-01 08:48 -0400 |
| Organization | A noiseless patient Spider |
| Message-ID | <jqadms$elk$1@dont-email.me> (permalink) |
| References | <3s7cs7hd18l0ffci55ns0286n4lc4cutlu@4ax.com> <f9064504-3948-43d4-b66e-55434a7a1ed1@googlegroups.com> <24hfs7hqsr75jmqgk87jcpfg85kif7nhuo@4ax.com> <jq8lij$g95$1@dont-email.me> <a2r4v1F3snU1@mid.individual.net> |
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
Back to comp.lang.java.programmer | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread
unchecked conversion warning. Jens - 2012-05-30 15:32 +0200
Re: unchecked conversion warning. Andreas Leitgeb <avl@gamma.logic.tuwien.ac.at> - 2012-05-30 13:48 +0000
Re: unchecked conversion warning. Jens - 2012-05-30 15:52 +0200
Re: unchecked conversion warning. Robert Klemme <shortcutter@googlemail.com> - 2012-05-30 07:54 -0700
Re: unchecked conversion warning. Jens - 2012-05-31 22:23 +0200
Re: unchecked conversion warning. Lew <lewbloch@gmail.com> - 2012-05-31 13:40 -0700
Re: unchecked conversion warning. Eric Sosman <esosman@ieee-dot-org.invalid> - 2012-05-31 16:50 -0400
Re: unchecked conversion warning. Lew <lewbloch@gmail.com> - 2012-05-31 17:18 -0700
Re: unchecked conversion warning. Robert Klemme <shortcutter@googlemail.com> - 2012-06-01 08:14 +0200
Re: unchecked conversion warning. Eric Sosman <esosman@ieee-dot-org.invalid> - 2012-06-01 08:48 -0400
Re: unchecked conversion warning. Robert Klemme <shortcutter@googlemail.com> - 2012-06-01 07:32 -0700
Re: unchecked conversion warning. Roedy Green <see_website@mindprod.com.invalid> - 2012-06-10 12:16 -0700
Re: unchecked conversion warning. Martin Gregorie <martin@address-in-sig.invalid> - 2012-06-10 22:08 +0000
Re: unchecked conversion warning. Lew <noone@lewscanon.com> - 2012-06-10 17:09 -0700
Re: unchecked conversion warning. Martin Gregorie <martin@address-in-sig.invalid> - 2012-06-11 01:31 +0000
Re: unchecked conversion warning. Jim Janney <jjanney@shell.xmission.com> - 2012-06-01 08:41 -0600
Re: unchecked conversion warning. Patricia Shanahan <pats@acm.org> - 2012-06-01 08:44 -0700
Re: unchecked conversion warning. markspace <-@.> - 2012-06-01 09:08 -0700
Re: unchecked conversion warning. Gene Wirchenko <genew@ocis.net> - 2012-06-01 09:31 -0700
Re: unchecked conversion warning. Jim Janney <jjanney@shell.xmission.com> - 2012-06-01 11:02 -0600
Re: unchecked conversion warning. Eric Sosman <esosman@ieee-dot-org.invalid> - 2012-06-01 13:54 -0400
Re: unchecked conversion warning. Patricia Shanahan <pats@acm.org> - 2012-06-01 16:44 -0700
Re: unchecked conversion warning. Eric Sosman <esosman@ieee-dot-org.invalid> - 2012-06-01 20:24 -0400
Re: unchecked conversion warning. Patricia Shanahan <pats@acm.org> - 2012-06-01 19:36 -0700
Re: natural/native language capabilities (was: unchecked conversion warning.) Jim Janney <jjanney@shell.xmission.com> - 2012-06-01 11:01 -0600
Re: unchecked conversion warning. Roedy Green <see_website@mindprod.com.invalid> - 2012-06-10 12:13 -0700
Re: unchecked conversion warning. Arne Vajhøj <arne@vajhoej.dk> - 2012-06-20 19:28 -0400
Re: unchecked conversion warning. Broad Liyn <broadliyn@gmail.com> - 2012-06-10 21:52 -0700
Re: unchecked conversion warning. Lew <noone@lewscanon.com> - 2012-06-10 23:50 -0700
Re: unchecked conversion warning. Patricia Shanahan <pats@acm.org> - 2012-06-11 00:06 -0700
Re: unchecked conversion warning. Robert Klemme <shortcutter@googlemail.com> - 2012-06-16 15:17 +0200
Re: unchecked conversion warning. Lew <lewbloch@gmail.com> - 2012-06-18 12:28 -0700
Re: unchecked conversion warning. Robert Klemme <shortcutter@googlemail.com> - 2012-06-19 23:14 +0200
Re: unchecked conversion warning. Lew <lewbloch@gmail.com> - 2012-06-19 17:15 -0700
Re: unchecked conversion warning. Arne Vajhøj <arne@vajhoej.dk> - 2012-06-20 19:22 -0400
Re: unchecked conversion warning. Arne Vajhøj <arne@vajhoej.dk> - 2012-06-20 19:20 -0400
csiph-web