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

RE: The comments are more important than the code

Expand Messages
  • Vlietstra, Joe (SSD)
    ... Sometimes comments are more important than the code. We have some very ugly code to control a DC power supply for spacecraft testing. Comments helped
    Message 1 of 8 , Apr 29, 2005
      --- "Tony Nassar" <devl@...> wrote:
      > To some developers, the comments *are* more important. More than
      > once, I've struggled with someone else's subroutine library (or
      > COM server...), for example, only to be asked, "Well, didn't you
      > "read my comments?" Apparently, it's not reasonable simply to
      > expect the code to *work*; you have to read about all the ways
      > it doesn't work, before you can safely use it.

      Sometimes comments are more important than the code.
      We have some very ugly code to control a DC power supply for
      spacecraft testing. Comments helped explain the ugliness --
      the interesting ways a test operator could incorrectly connect
      the DC power supply. The comments didn't explain the code, per
      se. They explained the constraints/requirements for the code.
      Because we have relatively little commenting in the code,
      the warning about the DC power supply jumps out.
    • Ian Collins
      ... Could this all be summed up as In legacy code, comments are often more important than the code. ? Do people agree that this is not the case for TDD
      Message 2 of 8 , Apr 29, 2005
        Vlietstra, Joe (SSD) wrote:

        >--- "Tony Nassar" <devl@...> wrote:
        >
        >
        >>To some developers, the comments *are* more important. More than
        >>once, I've struggled with someone else's subroutine library (or
        >>COM server...), for example, only to be asked, "Well, didn't you
        >>"read my comments?" Apparently, it's not reasonable simply to
        >>expect the code to *work*; you have to read about all the ways
        >>it doesn't work, before you can safely use it.
        >>
        >>
        >
        >Sometimes comments are more important than the code.
        >We have some very ugly code to control a DC power supply for
        >spacecraft testing. Comments helped explain the ugliness --
        >the interesting ways a test operator could incorrectly connect
        >the DC power supply. The comments didn't explain the code, per
        >se. They explained the constraints/requirements for the code.
        >Because we have relatively little commenting in the code,
        >the warning about the DC power supply jumps out.
        >
        >
        >
        Could this all be summed up as "In legacy code, comments are often more
        important than the code."?

        Do people agree that this is not the case for TDD produced code?

        Ian
      • Russel Hill
        ... Only when they are correct. The occasional, obvious, and important comment is quite likely to be correct. In legacy code, out of date comments are all to
        Message 3 of 8 , Apr 29, 2005
          On 4/29/05, Ian Collins <ian@...> wrote:
          > Could this all be summed up as "In legacy code, comments are often more
          > important than the code."?

          Only when they are correct.

          The occasional, obvious, and important comment is quite likely to be
          correct. In legacy code, out of date comments are all to likely to
          be sprinkled throughout like background noise.

          > Do people agree that this is not the case for TDD produced code?

          I wouldn't say so. In the cases where we've decided comments are
          necessary, they are important and obvious.
        • Edmund Schweppe
          ... Hmmm. It *could* be summed up that way, but I don t think that would be really accurate. The problem, as I see it, is that *useful* comments are valuable.
          Message 4 of 8 , Apr 29, 2005
            Ian Collins wrote:

            > Could this all be summed up as "In legacy code, comments are often more
            > important than the code."?

            Hmmm. It *could* be summed up that way, but I don't think that would be
            really accurate.

            The problem, as I see it, is that *useful* comments are valuable.
            Unfortunately, there's no obvious way (short of reading both a
            particular comment and the associated code) to tell if any given comment
            is actually useful. Meanwhile, far too many comments end up being not
            useful - sometimes due to once-useful comments not being updated over
            time, often due to the comments never having been useful in the first
            place.

            > Do people agree that this is not the case for TDD produced code?

            Tests and code together will *almost* always make comments unnecessary.
            But comments will still be needful from time to time. If nothing else,
            there's always the odd situation where you do something screwy to work
            around a bug in a particular deployment platform. (Even then, I'd want a
            test in addition. Sometimes, though, a test might not be practical...)
          • George Dinwiddie
            ... No, I once found some old out-of-date comments in some badly handled legacy code that was very valuable, because it told me what the original author had
            Message 5 of 8 , Apr 29, 2005
              Russel Hill wrote:
              > On 4/29/05, Ian Collins <ian@...> wrote:
              >
              >>Could this all be summed up as "In legacy code, comments are often more
              >>important than the code."?
              >
              >
              > Only when they are correct.

              No, I once found some old out-of-date comments in some badly handled
              legacy code that was very valuable, because it told me what the original
              author had intended before a stream of hacks had mucked it up.

              This could have been very important, had the company not laid me off a
              month later and gone out of business 6 months after that.

              - George

              --
              ----------------------------------------------------------------------
              When I remember bygone days George Dinwiddie
              I think how evening follows morn; iDIA Computing, LLC
              So many I loved were not yet dead, gdinwiddie@...
              So many I love were not yet born. http://www.idiacomputing.com
              'The Middle' by Ogden Nash http://www.agilemaryland.org
              ----------------------------------------------------------------------
            • Curtis Cooley
              ... Unfortuantely, my experience with legacy code and mandatory comments has much more often lead to this: /** /* @parameter sender the sender of the message
              Message 6 of 8 , Apr 30, 2005
                On 4/29/05, George Dinwiddie <programminglists@...> wrote:
                > Russel Hill wrote:
                > > On 4/29/05, Ian Collins <ian@...> wrote:
                > >
                > >>Could this all be summed up as "In legacy code, comments are often more
                > >>important than the code."?
                > >
                > >
                > > Only when they are correct.
                >
                > No, I once found some old out-of-date comments in some badly handled
                > legacy code that was very valuable, because it told me what the original
                > author had intended before a stream of hacks had mucked it up.
                >
                Unfortuantely, my experience with legacy code and mandatory comments
                has much more often lead to this:

                /**
                /* @parameter sender the sender of the message
                /* @parameter exceptionHandler handles any exceptions during message passing
                /* @parameter transport the transport to send the message through
                */
                public static void sendMessage(Object sender, IExceptionHandler
                handler, ITransport transport) {
                ...


                /**
                /* @parameter sender the sender of the message
                /* @parameter exceptionHandler handles any exceptions during message passing
                /* @parameter transport the transport to send the message through
                */
                public static void sendMessage(Object sender, IExceptionHandler handler) {
                ...

                Hmm, comments can be copy/pasted as well . . .

                --
                Curtis Cooley
                curtis.cooley@...
              • yahoogroups@jhrothjr.com
                From: George Dinwiddie To: extremeprogramming@yahoogroups.com
                Message 7 of 8 , Apr 30, 2005
                  From: "George Dinwiddie"
                  <programminglists.at.alberg30.org@...>
                  To: "extremeprogramming@yahoogroups.com"
                  <extremeprogramming.at.yahoogroups.com@...>
                  Sent: Friday, April 29, 2005 10:21 PM
                  Subject: Re: [XP] RE: The comments are more important than the code


                  > Russel Hill wrote:
                  >> On 4/29/05, Ian Collins <ian@...> wrote:
                  >>
                  >>>Could this all be summed up as "In legacy code, comments are often more
                  >>>important than the code."?
                  >>
                  >>
                  >> Only when they are correct.
                  >
                  > No, I once found some old out-of-date comments in some badly handled
                  > legacy code that was very valuable, because it told me what the original
                  > author had intended before a stream of hacks had mucked it up.

                  And definitely a valuable observation. However, let's do a bit
                  of taxonomy to maybe get some clarity.

                  Comments can deal with:

                  1. What the code is supposed to do (requirements)

                  2. How the code is supposed to do it (design)

                  3. Things in the code that may not be clear to the average
                  team member (more design)

                  4. Special cases that dictate one design over another in
                  view of the requirements.

                  In the above, 1 should be explicitly dealt with in the
                  executable acceptance tests.

                  2 should be dealt with by the combination of unit
                  tests and production code (in other words, readable
                  code).

                  3 should be expunged if at all possible.

                  4. Special cases and corner cases should be elevated to
                  the level of an executable acceptance test.

                  Does this make sense?

                  John Roth



                  >
                  > - George
                  >
                  > --
                  > ----------------------------------------------------------------------
                  > When I remember bygone days George Dinwiddie
                  > I think how evening follows morn; iDIA Computing, LLC
                  > So many I loved were not yet dead, gdinwiddie@...
                  > So many I love were not yet born. http://www.idiacomputing.com
                  > 'The Middle' by Ogden Nash http://www.agilemaryland.org
                  > ----------------------------------------------------------------------
                  >
                  >
                  >
                  >
                  >
                  > To Post a message, send it to: extremeprogramming@...
                  >
                  > To Unsubscribe, send a blank message to:
                  > extremeprogramming-unsubscribe@...
                  >
                  > ad-free courtesy of objectmentor.com
                  > Yahoo! Groups Links
                  >
                  >
                  >
                  >
                  >
                  >
                  >
                  >
                • Friedrich Brunzema
                  My experience has been that most of the time when I have really been tempted to write a comment in the code, there s a way to extract a well named method that
                  Message 8 of 8 , May 1, 2005
                    My experience has been that most of the time when I have really been
                    tempted to write a comment in the code, there's a way to extract a
                    well named method that gets rid of the comment. Cool thing about this
                    is you can't ignore, delete or change this type of comment because its
                    working code.

                    In some cases, when the pair has thought long and hard about getting
                    rid of the comment (and sometimes writing it first helps to focus what
                    you are trying to say), you realize that the situation is so weird
                    that you can't really express it in code. Since you want your code to
                    communicate intent, the only real option left is to add the comment.
                    Usually the quality of such a comment is so high, that people see its
                    value immediatley.

                    Friedrich Brunzema
                    Extreme Programmer & Coach

                    On 4/29/05, Ian Collins <ian@...> wrote:
                    > Vlietstra, Joe (SSD) wrote:
                    >
                    > >--- "Tony Nassar" <devl@...> wrote:
                    > >
                    > >
                    > >>To some developers, the comments *are* more important. More than
                    > >>once, I've struggled with someone else's subroutine library (or
                    > >>COM server...), for example, only to be asked, "Well, didn't you
                    > >>"read my comments?" Apparently, it's not reasonable simply to
                    > >>expect the code to *work*; you have to read about all the ways
                    > >>it doesn't work, before you can safely use it.
                    > >>
                    > >>
                    > >
                    > >Sometimes comments are more important than the code.
                    > >We have some very ugly code to control a DC power supply for
                    > >spacecraft testing. Comments helped explain the ugliness --
                    > >the interesting ways a test operator could incorrectly connect
                    > >the DC power supply. The comments didn't explain the code, per
                    > >se. They explained the constraints/requirements for the code.
                    > >Because we have relatively little commenting in the code,
                    > >the warning about the DC power supply jumps out.
                    > >
                    > >
                    > >
                    > Could this all be summed up as "In legacy code, comments are often more
                    > important than the code."?
                    >
                    > Do people agree that this is not the case for TDD produced code?
                    >
                    > Ian
                    >
                    >
                    > To Post a message, send it to: extremeprogramming@...
                    >
                    > To Unsubscribe, send a blank message to: extremeprogramming-unsubscribe@...
                    >
                    > ad-free courtesy of objectmentor.com
                    > Yahoo! Groups Links
                    >
                    >
                    >
                    >
                    >
                  Your message has been successfully submitted and would be delivered to recipients shortly.