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

RE: [XP] Comments

Expand Messages
  • Scott Jackson
    Wow!!! I m essentially a Lurker here (with a few occasional wise-cracks). First, if it is possible I would like to see this piece of code. Second, I feel that
    Message 1 of 48 , Jul 27, 2000
      Wow!!!

      I'm essentially a Lurker here (with a few occasional wise-cracks).
      First, if it is possible I would like to see this piece of code.
      Second, I feel that this person has provided everyone who will be
      using it a historical narrative of the reFactoring process he used.
      Maybe some feel that such a learning tool is superfluous; I would
      appreciate the opportunity to learn.

      As an aside, the book "Lincoln at Gettysburg
      The words that remade America
      By Garry Wills
      that I am currently reading struck me in a similar way: just the
      prologue
      has given me more insight and understanding of those words than I
      ever had before.

      Scott Jackson
      Process Engineer
      FastParts.com
      vox:408 360-1340
      fax: 408 360-9119


      -----Original Message-----
      From: Kent Quirk [mailto:kent_quirk@...]
      Sent: Thursday, July 27, 2000 8:27 AM
      To: extremeprogramming@egroups.com
      Subject: [XP] Comments


      I'm having some trouble with the principle that comments are generally
      counterproductive. I can see that:

      x++; // add one to x

      doesn't help much. :-)

      And for years, I haven't bothered with the thing that some companies
      I've worked for required, namely that each parameter to a method be
      documented in the comments to the method. I certainly like the idea that
      variable names should be self-explanatory.

      So in general, I don't often write comments in our code to explain
      "what" is happening. And I often remove useless comments. But answering
      the question "why" seems like a useful reason to comment things.

      I was just looking at a file in our source that contains about 30 lines
      of actual code. It's a utility function, implemented as a C++ template
      and an associated macro. (For the curious, it's called stringize, and
      converts any data type supporting operator<< to a string.)

      It's deceptively simple code -- extremely powerful, extremely useful,
      and fairly subtle. It was implemented by an expert programmer, and while
      I think that most reasonably competent C++ programmers could understand
      it and maintain it, few would have had the vision to implement it in
      that way. In fact, until he came along, we did the same general task
      with a far less useful but much larger collection of special-purpose
      utility functions, or by repeating the same three lines of boilerplate
      code in a lot of places. In other words, he refactored a lot of code out
      of existence with this file.

      My point is that stringize contains only 30 lines of executable code,
      and 100 lines of comments explaining why it was created, why it was
      created in this fashion, and the hacks that had to be used to get around
      a limitation in our compiler. There are no "what" comments, but a whole
      lot of "why" comments.

      If I were maintaining this code and didn't have the commentary, I'm sure
      that I would run down some of the same blind alleys he's already
      documented.

      So does anybody want to suggest that these comments should be removed?
      Because I don't.

      Kent

      --
      -----------------------------------------------------------------------
      Kent Quirk | CogniToy: Intelligent toys...
      Game Designer | for intelligent minds.
      kent_quirk@... | http://www.cognitoy.com/
      _____________________________|_________________________________________

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

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

      Ad-free courtesy of objectmentor.com
    • Bill dehOra
      ... Though it is a bit jarring, I can t see how this naming differentiates from other human-readable variable naming. Exceptions are not for expected
      Message 48 of 48 , Aug 1, 2000
        >> catch (InterruptedIOException ignoringNormalTimeOut)
        >>

        >I can't say I like that very much. It clouds the intent a
        >bit.

        Though it is a bit jarring, I can't see how this naming differentiates from
        other human-readable variable naming. Exceptions are not for expected
        behaviour. If there is an exception block that is not for exceptional
        behaviour (as above), then the naming above indicates the intent: the intent
        being that there isn't any.

        Of course it would be better if the try/catch block could be made to go away
        altogether, and java had cleaner exception objects.

        > I don't think a variable name should be solely a comment.

        But that's ok, it is a comment of sorts: this variable doesn't do anything
        at the programmers level of intent, other than get him or her out of a
        redundant contract.


        >Something that is solely
        >a comment should be a syntatic comment so that the reader knows you are
        >commenting on something.

        You're totally right, but redundant try/catch variables are an exception.

        -Bill de hÓra
      Your message has been successfully submitted and would be delivered to recipients shortly.