Loading ...
Sorry, an error occurred while loading the content.

RE: [XP] JavaDoc and XP

Expand Messages
  • Steven Gordon
    It is up to the customer to decide if redundant documentation is a requirement of sufficient value to pay for its cost. If they are paying for it, we fulfill
    Message 1 of 8 , May 30, 2003
    • 0 Attachment
      It is up to the customer to decide if redundant documentation is a
      requirement of sufficient value to pay for its cost. If they are paying for
      it, we fulfill it. That would not preclude me from outsourcing such a
      mundane task to somebody whose time is less costly like a student worker.

      -----Original Message-----
      From: Eric [mailto:cybermac912@...]
      Sent: Friday, May 30, 2003 2:21 PM
      To: extremeprogramming@yahoogroups.com
      Subject: [XP] JavaDoc and XP


      Hi,

      I'm having an argument with my manager right now, and I need to find
      some support for either of our positions. I've looked on the C2 Wiki
      and this group, but I haven't found an answer for this specific
      question.

      It goes like this: Supposing API documentation is a requirement for
      our product (off-the-shelf commercial), what would XP have to say
      about JavaDoc comments for *everything*?

      For instance, my feeling is that code like the following:
      /**
      * Returns the height of the Rectangle.
      * @return the Rectangle's height
      */
      public double getHeight() {
      return myHeight;
      }

      is redundant, wasteful, and irritating. Even in the API doc, it adds
      nothing that is not clear from the method signature itself.

      My manager has two arguments (needless to say, I disagree with both
      of them).

      1) In the documentation's method listings:
      -------------------------------------------------------------------
      | double | getHeight() |
      | | Returns the height of the Rectangle. |
      -------------------------------------------------------------------

      looks more professional than

      -------------------------------------------------------------------
      | double | getHeight() |
      -------------------------------------------------------------------

      2) Sun, IBM, etc. do that in their docs (The old "everyone else is
      doing it, so why shouldn't we" argument).

      Sorry for the long post, but I'd really like to get some help on
      this. I'm really struggling to get XP more fully implemented and keep
      it from getting lip-service only.

      Eric McIntyre
      Java Developer
      Island Pacific


      To Post a message, send it to: extremeprogramming@...

      To Unsubscribe, send a blank message to:
      extremeprogramming-unsubscribe@...

      ad-free courtesy of objectmentor.com

      Your use of Yahoo! Groups is subject to http://docs.yahoo.com/info/terms/



      [Non-text portions of this message have been removed]
    • Erik Hanson
      ... I disagree with him. #1 looks less professional to me because it is repetitious and redundant. Professional books have editors to remove duplication;
      Message 2 of 8 , May 30, 2003
      • 0 Attachment
        "Eric" <cybermac912@...> wrote:
        > My manager has two arguments (needless to say, I disagree with both
        > of them).
        >
        > 1) In the documentation's method listings:
        > -------------------------------------------------------------------
        > | double | getHeight() |
        > | | Returns the height of the Rectangle. |
        > -------------------------------------------------------------------
        >
        > looks more professional than
        >
        > -------------------------------------------------------------------
        > | double | getHeight() |
        > -------------------------------------------------------------------

        I disagree with him. #1 looks less professional to me because it is
        repetitious and redundant. Professional books have editors to remove
        duplication; professional-looking documentation shouldn't have duplication
        either.

        Besides, in 3 months, the comment is going to look like:

        -------------------------------------------------------------------
        | double | getYOffset() |
        | | Returns the height of the Rectangle |
        -------------------------------------------------------------------

        (And the method will have been moved to Shape, making it doubly wrong.)

        If you need more than just my word for it (and I can't imagine why anyone
        would ;), you could create a new poll on this mailing list: "As a software
        engineering professional, which type of documentation would you rather
        read?" I'd bet Madonna's house that the less repetitious way would win.


        > 2) Sun, IBM, etc. do that in their docs (The old "everyone else is
        > doing it, so why shouldn't we" argument).

        If I had to guess (without being encumbered by any facts), I'd guess that
        Sun and IBM are less likely to be agile than "HyperPhreak Software, Inc."
        Big and un-agile has a place perhaps, but you may not want to be in that
        place.



        > Sorry for the long post, but I'd really like to get some help on
        > this. I'm really struggling to get XP more fully implemented and keep
        > it from getting lip-service only.

        Good luck. It's not always an easy road...



        Erik Hanson
      • Eric
        ... both ... - ... - ... - ... - ... duplication ... wrong.) ... anyone ... software ... rather ... win. ... guess that ... Inc. ... that ... keep ... Thank
        Message 3 of 8 , May 30, 2003
        • 0 Attachment
          --- In extremeprogramming@yahoogroups.com, "Erik Hanson"
          <yahoogroups@e...> wrote:
          > "Eric" <cybermac912@y...> wrote:
          > > My manager has two arguments (needless to say, I disagree with
          both
          > > of them).
          > >
          > > 1) In the documentation's method listings:
          > > ------------------------------------------------------------------
          -
          > > | double | getHeight()
          |
          > > | | Returns the height of the Rectangle.
          |
          > > ------------------------------------------------------------------
          -
          > >
          > > looks more professional than
          > >
          > > ------------------------------------------------------------------
          -
          > > | double | getHeight()
          |
          > > ------------------------------------------------------------------
          -
          >
          > I disagree with him. #1 looks less professional to me because it is
          > repetitious and redundant. Professional books have editors to remove
          > duplication; professional-looking documentation shouldn't have
          duplication
          > either.
          >
          > Besides, in 3 months, the comment is going to look like:
          >
          > -------------------------------------------------------------------
          > | double | getYOffset() |
          > | | Returns the height of the Rectangle |
          > -------------------------------------------------------------------
          >
          > (And the method will have been moved to Shape, making it doubly
          wrong.)
          >
          > If you need more than just my word for it (and I can't imagine why
          anyone
          > would ;), you could create a new poll on this mailing list: "As a
          software
          > engineering professional, which type of documentation would you
          rather
          > read?" I'd bet Madonna's house that the less repetitious way would
          win.
          >
          >
          > > 2) Sun, IBM, etc. do that in their docs (The old "everyone else is
          > > doing it, so why shouldn't we" argument).
          >
          > If I had to guess (without being encumbered by any facts), I'd
          guess that
          > Sun and IBM are less likely to be agile than "HyperPhreak Software,
          Inc."
          > Big and un-agile has a place perhaps, but you may not want to be in
          that
          > place.
          >
          >
          >
          > > Sorry for the long post, but I'd really like to get some help on
          > > this. I'm really struggling to get XP more fully implemented and
          keep
          > > it from getting lip-service only.
          >
          > Good luck. It's not always an easy road...
          >
          >
          >
          > Erik Hanson

          Thank you, not only for your reply, but for taking my side ;-) I
          think I'll try your poll suggestion.

          Eric
        • Michael Lee
          That s why we have pair programming to ensure that code is of a certain quality. Developers must be pairing on any production code :-) ... From: Eric
          Message 4 of 8 , May 30, 2003
          • 0 Attachment
            That's why we have pair programming to ensure that code is of a certain
            quality. Developers must be pairing on any production code :-)

            ----- Original Message -----
            From: "Eric" <cybermac912@...>
            To: <extremeprogramming@yahoogroups.com>
            Sent: Saturday, May 31, 2003 9:05 AM
            Subject: Re: [XP] JavaDoc and XP


            > --- In extremeprogramming@yahoogroups.com, Johan Lindstrom
            > <johanl@b...> wrote:
            > > At 21:21 2003-05-30 +0000, Eric wrote:
            > >
            > > The signature doesn't say if the method does something else than
            > the
            > > obvious. The comment says explicitly that it doesn't. So it's not
            > redundant.
            > >
            > > I like explicit, especially in APIs.
            >
            > Hmm, interesting point, but I don't think it quite changes my mind.
            > If the developer is disciplined enough to keep the comment up-to-date
            > when the code changes, then, IMHO, the developer is disciplined
            > enough to rename/refactor the method as needed. Usually hidden
            > behavior is a bad smell.
            >
            > I suppose it boils down to a trust issue: Do we trust our development
            > team to be disciplined about method naming, refactoring, adding
            > comments when necessary, etc.? Do the consumers of the docs (new
            > hires, contractors, customers, etc.) trust that we are good
            > developers that always do the right thing instead of the easiest
            > thing? In any case, if the trust isn't there, the comments add no
            > benefit.
            >
            > >
            > > What is missing is e.g. the unit the measure is in. Is it cm or
            > > nanoparsecs? Or is that also obvious from the context? Oh, pixels.
            >
            >
            >
            >
            > To Post a message, send it to: extremeprogramming@...
            >
            > To Unsubscribe, send a blank message to:
            extremeprogramming-unsubscribe@...
            >
            > ad-free courtesy of objectmentor.com
            >
            > Your use of Yahoo! Groups is subject to http://docs.yahoo.com/info/terms/
            >
            >
            >
            >
          • Edmund Schweppe
            ... I suspect it depends on whether everything means everything in the published API or everything, visible or not, anywhere in the codebase . ... Agreed;
            Message 5 of 8 , May 30, 2003
            • 0 Attachment
              Eric wrote:
              >
              > Hi,
              >
              > I'm having an argument with my manager right now, and I need to find
              > some support for either of our positions. I've looked on the C2 Wiki
              > and this group, but I haven't found an answer for this specific
              > question.
              >
              > It goes like this: Supposing API documentation is a requirement for
              > our product (off-the-shelf commercial), what would XP have to say
              > about JavaDoc comments for *everything*?

              I suspect it depends on whether "everything" means "everything in the
              published API" or "everything, visible or not, anywhere in the
              codebase".

              > For instance, my feeling is that code like the following:
              > /**
              > * Returns the height of the Rectangle.
              > * @return the Rectangle's height
              > */
              > public double getHeight() {
              > return myHeight;
              > }
              >
              > is redundant, wasteful, and irritating. Even in the API doc, it adds
              > nothing that is not clear from the method signature itself.

              Agreed; however, I'd consider that a bug in the particular doc comment
              rather than a bug in the "JavaDocs required" process. In this particular
              case, I'd want to know what the units are, what a negative height means,
              what a zero height means, and (since it's a double) what a NaN would
              mean. Plus, I'd like to know whether this value is likely to change if I
              do something else to the Rectangle object.

              > My manager has two arguments (needless to say, I disagree with both
              > of them).
              >
              > 1) In the documentation's method listings:
              > -------------------------------------------------------------------
              > | double | getHeight() |
              > | | Returns the height of the Rectangle. |
              > -------------------------------------------------------------------
              >
              > looks more professional than
              >
              > -------------------------------------------------------------------
              > | double | getHeight() |
              > -------------------------------------------------------------------

              I agree with your manager that blanks in JavaDocs of published APIs look
              scruffy. Blanks in JavaDocs generally tell me that I need to go talk to
              the developers if I have any questions. This isn't an issue for me if
              the developers are part of my team; this is a *big* issue for me if I've
              already paid a vendor a bunch of money for the product and the
              developers are part of the *vendor's* team.

              I agree with you that "Returns the height of the Rectangle" is nearly
              worthless as documentation. I've seen the equivalent before, and it
              irritates the hell out of me. That sort of doc comment tells me that the
              vendor's people were *just* writing JavaDocs to avoid having blanks.

              If I was a developer coding against your API, I'd really want to see
              something like this:

              -------------------------------------------------------------------
              | double | getHeight() |
              | | Returns the height of the Rectangle, in the units |
              | | specified by getUnit(). Changing the measurement |
              | | unit by calling setUnit() will change what this |
              | | method returns. |
              | | Will never return a negative or zero value. |
              | | Returns NaN if no height has been specified by a |
              | | call to setHeight(), or if that value was zero or |
              | | negative. |
              -------------------------------------------------------------------

              (assuming, of course, that's the behavior of the method and the object)

              > 2) Sun, IBM, etc. do that in their docs (The old "everyone else is
              > doing it, so why shouldn't we" argument).

              Yep. Again, I agree that writing stupid comments is a bad idea. In the
              case of published APIs, I think that providing blank JavaDocs is as bad
              an idea as providing stupid ones, and I'd urge you to do neither.

              The case of code for internal use only, however, is a different kettle
              of fish.

              Hope this was helpful.

              --
              Edmund Schweppe -- schweppe@... -- http://schweppe.home.tiac.net
              The opinions expressed herein are at best coincidentally related to
              those of any past, present or future employer.
            • yahoogroups@jhrothjr.com
              ... From: Johan Lindstrom To: extremeprogramming@yahoogroups.com
              Message 6 of 8 , May 30, 2003
              • 0 Attachment
                ----- Original Message -----
                From: "Johan Lindstrom" <johanl.at.bahnhof.se@...>
                To: "extremeprogramming@yahoogroups.com"
                <extremeprogramming.at.yahoogroups.com@...>
                Sent: Friday, May 30, 2003 6:41 PM
                Subject: Re: [XP] JavaDoc and XP


                > At 21:21 2003-05-30 +0000, Eric wrote:
                > >is redundant, wasteful, and irritating. Even in the API doc, it adds
                > >nothing that is not clear from the method signature itself.
                >
                > The signature doesn't say if the method does something else than the
                > obvious. The comment says explicitly that it doesn't. So it's not
                redundant.
                >
                > I like explicit, especially in APIs.
                >
                > What is missing is e.g. the unit the measure is in. Is it cm or
                > nanoparsecs? Or is that also obvious from the context? Oh, pixels.

                Since this is Java, with a static type system, you can use well named
                types for that kind of information. It becomes part of the signature.

                John Roth
                >
                >
                > /J
                >
                > -------- ------ ---- --- -- -- -- - - - - -
                > Johan Lindström Sourcerer @ Boss Casinos johanl@...
                >
              • Keith Ray
                On Friday, May 30, 2003, at 03:02 PM, Erik Hanson
                Message 7 of 8 , May 30, 2003
                • 0 Attachment
                  On Friday, May 30, 2003, at 03:02 PM, Erik Hanson <... e.lafromage.com
                  >wrote:
                  [....]

                  Nice website, Erik. Good example of succinct documentation.

                  http://www.lafromage.com/


                  --
                  C. Keith Ray
                  <http://homepage.mac.com/keithray/blog/index.html>
                  <http://homepage.mac.com/keithray/xpminifaq.html>
                  <http://homepage.mac.com/keithray/resume.html>
                • Steven Gordon
                  For some reason this email got distributed 34 hours after I sent it - sorry for its lack of timeliness. ... From: Steven Gordon [mailto:sagordon@asu.edu] Sent:
                  Message 8 of 8 , Jun 1, 2003
                  • 0 Attachment
                    For some reason this email got distributed 34 hours after I sent it - sorry
                    for its lack of timeliness.

                    -----Original Message-----
                    From: Steven Gordon [mailto:sagordon@...]
                    Sent: Fri 5/30/2003 2:36 PM
                    To: 'extremeprogramming@yahoogroups.com'
                    Cc:
                    Subject: RE: [XP] JavaDoc and XP

                    It is up to the customer to decide if redundant documentation is a
                    requirement of sufficient value to pay for its cost. If they are paying for
                    it, we fulfill it. That would not preclude me from outsourcing such a
                    mundane task to somebody whose time is less costly like a student worker.

                    -----Original Message-----
                    From: Eric [mailto:cybermac912@...]
                    Sent: Friday, May 30, 2003 2:21 PM
                    To: extremeprogramming@yahoogroups.com
                    Subject: [XP] JavaDoc and XP


                    Hi,

                    I'm having an argument with my manager right now, and I need to find
                    some support for either of our positions. I've looked on the C2 Wiki
                    and this group, but I haven't found an answer for this specific
                    question.

                    It goes like this: Supposing API documentation is a requirement for
                    our product (off-the-shelf commercial), what would XP have to say
                    about JavaDoc comments for *everything*?

                    For instance, my feeling is that code like the following:
                    /**
                    * Returns the height of the Rectangle.
                    * @return the Rectangle's height
                    */
                    public double getHeight() {
                    return myHeight;
                    }

                    is redundant, wasteful, and irritating. Even in the API doc, it adds
                    nothing that is not clear from the method signature itself.

                    My manager has two arguments (needless to say, I disagree with both
                    of them).

                    1) In the documentation's method listings:
                    -------------------------------------------------------------------
                    | double | getHeight() |
                    | | Returns the height of the Rectangle. |
                    -------------------------------------------------------------------

                    looks more professional than

                    -------------------------------------------------------------------
                    | double | getHeight() |
                    -------------------------------------------------------------------

                    2) Sun, IBM, etc. do that in their docs (The old "everyone else is
                    doing it, so why shouldn't we" argument).

                    Sorry for the long post, but I'd really like to get some help on
                    this. I'm really struggling to get XP more fully implemented and keep
                    it from getting lip-service only.

                    Eric McIntyre
                    Java Developer
                    Island Pacific


                    To Post a message, send it to: extremeprogramming@...

                    To Unsubscribe, send a blank message to:
                    extremeprogramming-unsubscribe@...

                    ad-free courtesy of objectmentor.com

                    Your use of Yahoo! Groups is subject to http://docs.yahoo.com/info/terms/



                    [Non-text portions of this message have been removed]


                    To Post a message, send it to: extremeprogramming@...

                    To Unsubscribe, send a blank message to:
                    extremeprogramming-unsubscribe@...

                    ad-free courtesy of objectmentor.com

                    Your use of Yahoo! Groups is subject to http://docs.yahoo.com/info/terms/




                    [Non-text portions of this message have been removed]
                  Your message has been successfully submitted and would be delivered to recipients shortly.