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

Re: [XP] Re: Necessary comments?

Expand Messages
  • J. B. Rainsberger
    ... I have one suggestion: name the function safeTextContains() so that it is clear in at the call sites that this is not your ordinarily text pattern matching
    Message 1 of 21 , Oct 1, 2003
    • 0 Attachment
      Chris Riesbeck wrote:

      >> Date: Wed, 1 Oct 2003 06:59:53 -0400
      >> From: Ron Jeffries <ronjeffries@...>
      >>
      >>So I would love to see a snippet of code from someone including a valuable
      >>comment saying WHY it should happen that way.
      >>
      >>Then, of course, we'll try to refactor it to see how much of the comment
      >>can be reflected in the code, and how much cannot.
      >
      >
      > In Javascript, if rexp is a regular expression object,
      > rexp.test(text) returns true if text contains a match for rexp. But
      > on at least one browser platform, this blows up if text is an empty
      > string, so I had to define and call the following:
      >
      > // IE 5 on a Mac runs out of memory with rexp.text("")
      > // or "".search(rexp) !!
      >
      > function textContains(text, rexp) {
      > return text != "" && rexp.test(text);
      > }
      >
      > Since the empty string should fail the test anyway, and this bug
      > doesn't happen on most platforms, I figured I needed the comment to
      > make sure no one optimized away this unnecessary function.
      >
      > I could've called the function textContainThatWorksInIE5Mac but that
      > doesn't seem like a win to me. It might not even be the right name
      > since maybe it happens in Safari or some Linux browser or...

      I have one suggestion: name the function safeTextContains() so that it
      is clear in at the call sites that this is not your ordinarily text
      pattern matching function. The reader will ask herself, "What could be
      unsafe about it?" and consult the function definition, which improves
      the odds of someone reading the comment before deciding to refactor away
      "this nonsense".

      But I can't do much with the function itself. I would change the
      comment, though, to

      // regexp.text("") and "".search(regexp) run out of memory
      // on some platforms (example: IE 5 on Mac)

      This better reflects what you wrote when you explained the comment.
      Surely the comment ought not to need a comment! :)

      --
      J. B. Rainsberger,
      Diaspar Software Services
      http://www.diasparsoftware.com :: +1 416 791-8603
      Let's write software that people understand
    • Steven Gordon
      It would seem that your comment suffers from the same deficiency you identified for the function name textContainThatWorksInIE5Mac. If even today you are
      Message 2 of 21 , Oct 1, 2003
      • 0 Attachment
        It would seem that your comment suffers from the same deficiency you identified for the function name textContainThatWorksInIE5Mac. If even today you are unsure if it is only a problem with IE5 on the Mac, do you have to express more information than you are sure of?

        Why not:

        const string EMPTY_STRING_SOMETIMES_BLOWS_MEMORY = "";

        function textContains(text, rexp) {
        return text != EMPTY_STRING_SOMETIMES_BLOWS_MEMORY && rexp.test(text);
        }

        PS: What if the regular expression happens to include the empty string?

        -----Original Message-----
        From: Chris Riesbeck [mailto:riesbeck@...]
        Sent: Wed 10/1/2003 2:13 PM
        To: extremeprogramming@yahoogroups.com
        Cc:
        Subject: [XP] Re: Necessary comments?



        > Date: Wed, 1 Oct 2003 06:59:53 -0400
        > From: Ron Jeffries <ronjeffries@...>
        >
        >So I would love to see a snippet of code from someone including a valuable
        >comment saying WHY it should happen that way.
        >
        >Then, of course, we'll try to refactor it to see how much of the comment
        >can be reflected in the code, and how much cannot.

        In Javascript, if rexp is a regular expression object,
        rexp.test(text) returns true if text contains a match for rexp. But
        on at least one browser platform, this blows up if text is an empty
        string, so I had to define and call the following:

        // IE 5 on a Mac runs out of memory with rexp.text("")
        // or "".search(rexp) !!

        function textContains(text, rexp) {
        return text != "" && rexp.test(text);
        }

        Since the empty string should fail the test anyway, and this bug
        doesn't happen on most platforms, I figured I needed the comment to
        make sure no one optimized away this unnecessary function.

        I could've called the function textContainThatWorksInIE5Mac but that
        doesn't seem like a win to me. It might not even be the right name
        since maybe it happens in Safari or some Linux browser or...


        --


        Chris Riesbeck
        -----------------------------------------
        Home Page: http://www.cs.northwestern.edu/~riesbeck/
        Calendar: http://calendar.yahoo.com/criesbeck
        -----------------------------------------

        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]
      • Ron Jeffries
        ... Good start! I was stumped for a way to put it in the code. Ron Jeffries www.XProgramming.com This is how I develop software. Take the parts that make sense
        Message 3 of 21 , Oct 1, 2003
        • 0 Attachment
          On Wednesday, October 1, 2003, at 6:37:40 PM, Steven Gordon wrote:

          > const string EMPTY_STRING_SOMETIMES_BLOWS_MEMORY = "";



          > function textContains(text, rexp) {

          > return text != EMPTY_STRING_SOMETIMES_BLOWS_MEMORY && rexp.test(text);

          > }

          Good start! I was stumped for a way to put it in the code.

          Ron Jeffries
          www.XProgramming.com
          This is how I develop software.
          Take the parts that make sense to you.
          Ignore the rest.
        • Dale Emery
          ... In each case, I m thinking that a good test would help a little, a test that establishes or simulates the offending environment (Mac IE 5, depleted DMA
          Message 4 of 21 , Oct 2, 2003
          • 0 Attachment
            Chris wrote:
            > // IE 5 on a Mac runs out of memory with rexp.text("")
            > // or "".search(rexp) !!
            >
            > function textContains(text, rexp) {
            > return text != "" && rexp.test(text);
            > }

            Robert wrote:
            > /* We could've used callChain instead, but we don't know
            > * if there is any room in the DMA call stack left */
            > masterChain.appendChain(someCommandChain);

            In each case, I'm thinking that a good test would help a little,
            a test that establishes or simulates the offending environment
            (Mac IE 5, depleted DMA call stack space) and runs the code with
            the offending parameters (empty string, command chain that would
            overrun the stack). That would describe the condition that
            motivated the code, and give quick feedback if someone were to
            change the code.

            Though a good test would help a little, I'm guessing it wouldn't
            be /sufficiently/ expressive. For one thing, the test is in a
            different place than the code, which limits the help it offers.
            And if some programmers change the code to the more obvious (but
            wrong) logic, thus causing the test to fail, they would likely
            have to do some detective work to rediscover the motivation for
            the original code.

            What makes the detective work necessary in each of these cases is
            that the problem isn't directly present in the code; it's in the
            /environment/. Or perhaps it's in the programmers'
            reasonable-but-unwarranted assumptions about the environment.
            Are there any common solutions for this, common comment-free ways
            to express code quirks motivated by quirky environments?

            Dale

            --
            Dale Emery -- Consultant -- Resistance as a Resource
            Web: http://www.dhemery.com
            Weblog: http://www.dhemery.com/journal (Conversations with Dale)
          • Ron Jeffries
            ... I like the suggestions of naming a string variable, though of course the paragraph-long names are, I hope, offered at least partly in jest. My reasons for
            Message 5 of 21 , Oct 2, 2003
            • 0 Attachment
              On Wednesday, October 1, 2003, at 5:13:36 PM, Chris Riesbeck wrote:

              > // IE 5 on a Mac runs out of memory with rexp.text("")
              > // or "".search(rexp) !!

              > function textContains(text, rexp) {
              > return text != "" && rexp.test(text);
              > }

              I like the suggestions of naming a string variable, though of course the
              paragraph-long names are, I hope, offered at least partly in jest. My
              reasons for liking that kind of solution are these:

              1. Focusing on getting rid of /every/ comment is good exercise in learning
              to make code communicate. It doesn't take long, and the thought process is
              valuable.

              2. The code is less likely to be changed when it clearly says "don't touch
              me", than if it's just fenced by a comment.

              Another slight twist might be to expand the code to include a Guard Clause,
              along these lines:

              function textContains(text, rexp) {
              if (text == MacIE5BugText) return false;
              return rexp.test(text);
              }

              I'd also be tempted to write a unit test that fails on certain
              configurations, to verify the bug and perhaps to decide to remove the hack.
              Although I might be afraid /ever/ to remove the hack.

              Ron Jeffries
              www.XProgramming.com
              Wisdom begins when we discover the difference between
              "That makes no sense" and "I don't understand". --Mary Doria Russell
            • criesbeck
              ... with ... would ... In principle this sounds right -- a test that verifies that the code works for an empty string on a Mac with IE 5. But in practice I
              Message 6 of 21 , Oct 2, 2003
              • 0 Attachment
                --- In extremeprogramming@yahoogroups.com, Dale Emery
                <dale@d...> wrote:
                >
                > In each case, I'm thinking that a good test would help a little,
                > a test that establishes or simulates the offending environment
                > (Mac IE 5, depleted DMA call stack space) and runs the code
                with
                > the offending parameters (empty string, command chain that
                would
                > overrun the stack).

                In principle this sounds right -- a test that verifies that the code
                works for an empty string on a Mac with IE 5. But in practice I
                don't see how to write a test that will fail when run by a developer
                on a PC if internally the code doesn't handle the empty string
                specially. And that's the problem - the test will only show the bug
                on certain platforms.

                > Though a good test would help a little, I'm guessing it wouldn't
                > be /sufficiently/ expressive. For one thing, the test is in a
                > different place than the code, which limits the help it offers.
                > ... the problem isn't directly present in the code; it's in the
                > /environment/.
                >
                > Are there any common solutions for this, common
                comment-free ways
                > to express code quirks motivated by quirky environments?

                Well, you can write explicit platform tests in the code, a la those
                ever popular preprocessor macros in C, and browser-sniffing
                code in a lot of Javascript before browsers started converging
                toward a standard. More generally, I could've written

                function textContains(text, rexp) {
                if (BROWSER_HAS_EMPTY_STRING_REXP_BUG) {
                return text != "" && rexp.test(text);
                }
                else {
                return rexp.test(text);
                }
                }

                But I could imagine needing a comment saying "leave this in to
                document the problem..."
              • J. B. Rainsberger
                ... I don t think it s a good start. Now the code just reads like a comment, but the comment is still there. I don t believe that the name of the variable
                Message 7 of 21 , Oct 2, 2003
                • 0 Attachment
                  Ron Jeffries wrote:

                  > On Wednesday, October 1, 2003, at 6:37:40 PM, Steven Gordon wrote:
                  >
                  >
                  >>const string EMPTY_STRING_SOMETIMES_BLOWS_MEMORY = "";
                  >
                  >>function textContains(text, rexp) {
                  >> return text != EMPTY_STRING_SOMETIMES_BLOWS_MEMORY && rexp.test(text);
                  >>}
                  >
                  > Good start! I was stumped for a way to put it in the code.

                  I don't think it's a good start. Now the code just reads like a comment,
                  but the comment is still there. I don't believe that the name of the
                  variable reveals the intent of the variable.

                  I wanted to extract a guard clause and name it accordingly, like this:

                  function textContains(text, regexp) {
                  if (needToGuardAgainstOutOfMemory(text, regexp)) return;
                  return regexp.test(text);
                  }

                  function needToGuardAgainstOutOfMemory(text, regexp) {
                  return text == "";
                  }

                  But I would still want a comment describing why this is guarding against
                  OutOfMemory.

                  To me, the name of that constant above is just a transcription of, but
                  not an elimination of, the comment.
                  --
                  J. B. Rainsberger,
                  Diaspar Software Services
                  http://www.diasparsoftware.com :: +1 416 791-8603
                  Let's write software that people understand
                • Steven Gordon
                  The point is this. When the time comes that IE6 or 7 or whatever can handle empty strings on all platforms, and somebody comes along and updates the code
                  Message 8 of 21 , Oct 2, 2003
                  • 0 Attachment
                    The point is this. When the time comes that IE6 or 7 or whatever can handle empty strings on all platforms, and somebody comes along and updates the code accordingly, that person will be far more likley to eliminate the now unnecessary variable (whose name looks like a comment) than to eliminate the now unnecessary comment. Over time, this leads to false and misleading comments. This is why I would rather have variable names that look like comments than comments.

                    BTW, why is rexp a parameter to needToGuardAgainstOutOfMemory()?

                    And again, we are ignoring the case where the rexp happens to accept the empty string. We need to at least have a test that shows the function returns false in this case even thought we would normally expect it to return true.


                    -----Original Message-----
                    From: J. B. Rainsberger [mailto:jbrains@...]
                    Sent: Thu 10/2/2003 9:01 AM
                    To: extremeprogramming@yahoogroups.com
                    Cc:
                    Subject: Re: [XP] Re: Necessary comments?

                    Ron Jeffries wrote:

                    > On Wednesday, October 1, 2003, at 6:37:40 PM, Steven Gordon wrote:
                    >
                    >
                    >>const string EMPTY_STRING_SOMETIMES_BLOWS_MEMORY = "";
                    >
                    >>function textContains(text, rexp) {
                    >> return text != EMPTY_STRING_SOMETIMES_BLOWS_MEMORY && rexp.test(text);
                    >>}
                    >
                    > Good start! I was stumped for a way to put it in the code.

                    I don't think it's a good start. Now the code just reads like a comment,
                    but the comment is still there. I don't believe that the name of the
                    variable reveals the intent of the variable.

                    I wanted to extract a guard clause and name it accordingly, like this:

                    function textContains(text, regexp) {
                    if (needToGuardAgainstOutOfMemory(text, regexp)) return;
                    return regexp.test(text);
                    }

                    function needToGuardAgainstOutOfMemory(text, regexp) {
                    return text == "";
                    }

                    But I would still want a comment describing why this is guarding against
                    OutOfMemory.

                    To me, the name of that constant above is just a transcription of, but
                    not an elimination of, the comment.
                    --
                    J. B. Rainsberger,
                    Diaspar Software Services
                    http://www.diasparsoftware.com :: +1 416 791-8603
                    Let's write software that people understand


                    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]
                  • Ron Jeffries
                    ... Yes. Except that the transcription compiles and runs, and the comment does neither. That s why just might not be just right. Ron Jeffries
                    Message 9 of 21 , Oct 2, 2003
                    • 0 Attachment
                      On Thursday, October 2, 2003, at 12:01:07 PM, J. B. Rainsberger wrote:

                      > To me, the name of that constant above is just a transcription of, but
                      > not an elimination of, the comment.

                      Yes. Except that the transcription compiles and runs, and the comment does
                      neither. That's why "just" might not be "just" right.

                      Ron Jeffries
                      www.XProgramming.com
                      Knowledge must come through action;
                      you can have no test which is not fanciful, save by trial. -- Sophocles
                    • yahoogroups@jhrothjr.com
                      ... From: Ron Jeffries To: extremeprogramming@yahoogroups.com
                      Message 10 of 21 , Oct 2, 2003
                      • 0 Attachment
                        ----- Original Message -----
                        From: "Ron Jeffries"
                        <ronjeffries.at.XProgramming.com@...>
                        To: "extremeprogramming@yahoogroups.com"
                        <extremeprogramming.at.yahoogroups.com@...>
                        Sent: Thursday, October 02, 2003 1:39 PM
                        Subject: Re: [XP] Re: Necessary comments?


                        > On Thursday, October 2, 2003, at 12:01:07 PM, J. B. Rainsberger wrote:
                        >
                        > > To me, the name of that constant above is just a transcription of, but
                        > > not an elimination of, the comment.
                        >
                        > Yes. Except that the transcription compiles and runs, and the comment does
                        > neither. That's why "just" might not be "just" right.

                        The other thought I have on this is that JB said the name didn't say "why."
                        But then, the comment didn't either. I think "why" is important, but in this
                        case it's six of one and half a dozen of the other.

                        John Roth
                        >
                        > Ron Jeffries
                        > www.XProgramming.com
                        > Knowledge must come through action;
                        > you can have no test which is not fanciful, save by trial. -- Sophocles
                        >
                        >
                        > 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/
                        >
                        >
                      • J. B. Rainsberger
                        ... I think that if the variable name is just going to look like a comment, then maybe it is better to have the comment. That s pure opinion. I want names that
                        Message 11 of 21 , Oct 2, 2003
                        • 0 Attachment
                          Steven Gordon wrote:
                          > The point is this. When the time comes that IE6 or 7 or whatever can handle empty strings on all platforms, and somebody comes along and updates the code accordingly, that person will be far more likley to eliminate the now unnecessary variable (whose name looks like a comment) than to eliminate the now unnecessary comment. Over time, this leads to false and misleading comments. This is why I would rather have variable names that look like comments than comments.

                          I think that if the variable name is just going to look like a comment,
                          then maybe it is better to have the comment. That's pure opinion. I want
                          names that reveal intent, and I didn't think this variable name does
                          that. The best way I could reveal my intent is to write this as a guard
                          clause.

                          > BTW, why is rexp a parameter to needToGuardAgainstOutOfMemory()?

                          If it doesn't need to be, then remove it.

                          > And again, we are ignoring the case where the rexp happens to accept the empty string.

                          That's probably why regexp (not rexp -- my choice of name) was a
                          parameter to the guard clause function. I accidentally looked ahead. :)

                          > We need to at least have a test that shows the function returns false in this case even thought we would normally expect it to return true.

                          I agree that tests plus intentional code is the best solution to this
                          particular problem.
                          --
                          J. B. Rainsberger,
                          Diaspar Software Services
                          http://www.diasparsoftware.com :: +1 416 791-8603
                          Let's write software that people understand
                        • J. B. Rainsberger
                          ... Compilable comments are better than not-compilable comments. I ll buy that. I prefer the guard clause, though, as I prefer the way it reveals intent. Great
                          Message 12 of 21 , Oct 2, 2003
                          • 0 Attachment
                            Ron Jeffries wrote:

                            > On Thursday, October 2, 2003, at 12:01:07 PM, J. B. Rainsberger wrote:
                            >
                            >>To me, the name of that constant above is just a transcription of, but
                            >>not an elimination of, the comment.
                            >
                            > Yes. Except that the transcription compiles and runs, and the comment does
                            > neither. That's why "just" might not be "just" right.

                            Compilable comments are better than not-compilable comments. I'll buy that.

                            I prefer the guard clause, though, as I prefer the way it reveals
                            intent. Great minds think alike.
                            --
                            J. B. Rainsberger,
                            Diaspar Software Services
                            http://www.diasparsoftware.com :: +1 416 791-8603
                            Let's write software that people understand
                          • Ron Jeffries
                            ... What would be more why than IEMacBug or whatever the comment says? It s true that one could write a paragraph somewhere. Is this the place? I m not sure
                            Message 13 of 21 , Oct 2, 2003
                            • 0 Attachment
                              On Thursday, October 2, 2003, at 2:03:39 PM, yahoogroups@... wrote:

                              > The other thought I have on this is that JB said the name didn't say "why."
                              > But then, the comment didn't either. I think "why" is important, but in this
                              > case it's six of one and half a dozen of the other.

                              What would be more "why" than IEMacBug or whatever the comment says? It's
                              true that one could write a paragraph somewhere. Is this the place? I'm not
                              sure -- it might be.

                              Ron Jeffries
                              www.XProgramming.com
                              Please state the nature of the development emergency. -- Ryan Ripley
                            • Ron Jeffries
                              ... Indeed. ;- Ron Jeffries www.XProgramming.com Hope is not a strategy. -- Michael Henos
                              Message 14 of 21 , Oct 2, 2003
                              • 0 Attachment
                                On Thursday, October 2, 2003, at 2:11:46 PM, J. B. Rainsberger wrote:

                                >> Yes. Except that the transcription compiles and runs, and the comment does
                                >> neither. That's why "just" might not be "just" right.

                                > Compilable comments are better than not-compilable comments. I'll buy that.

                                > I prefer the guard clause, though, as I prefer the way it reveals
                                > intent. Great minds think alike.

                                Indeed. ;->

                                Ron Jeffries
                                www.XProgramming.com
                                Hope is not a strategy. -- Michael Henos
                              • Dale Emery
                                Hi Chris, ... I wouldn t know how to simulate that particular Mac IE 5 quirk on a PC. If it s possible, that would be a good thing to do. Even if you can t do
                                Message 15 of 21 , Oct 2, 2003
                                • 0 Attachment
                                  Hi Chris,

                                  > In principle this sounds right -- a test that verifies that the
                                  > code works for an empty string on a Mac with IE 5. But in
                                  > practice I don't see how to write a test that will fail when
                                  > run by a developer on a PC if internally the code doesn't
                                  > handle the empty string specially.

                                  I wouldn't know how to simulate that particular Mac IE 5 quirk on
                                  a PC. If it's possible, that would be a good thing to do.

                                  Even if you can't do that, the error will show up as soon as you
                                  run the test on the offending platform. How often do you do that?

                                  Dale

                                  --
                                  Dale Emery -- Consultant -- Resistance as a Resource
                                  Web: http://www.dhemery.com
                                  Weblog: http://www.dhemery.com/journal (Conversations with Dale)
                                Your message has been successfully submitted and would be delivered to recipients shortly.