Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.java.programmer > #14978

Re: unchecked conversion warning.

Show all headers | View raw

On Friday, June 1, 2012 2:48:23 PM UTC+2, Eric Sosman wrote:
> 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.

I didn't but I was curios what you meant by that. :-)

>      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).

Right, still often mediocre docs are better than no docs.  I agree that a lot of people in the software industry can use some training when it comes to writing documentation (either in code or separate in office document formats).

>      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.

"broken" is not a property of the stream which can be learned via a method of the API so the comment is really only of limited usefulness.

>      Finally, don't overlook the smiley.

Huh, what smiley?

Cheers

robert

Back to comp.lang.java.programmer | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

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