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

74286RE: [XP] JavaDoc and XP

Expand Messages
  • Steven Gordon
    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]
    • Show all 8 messages in this topic