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

Re: [XP] RE: The comments are more important than the code

Expand Messages
  • 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 1 of 8 , May 1, 2005
    • 0 Attachment
      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.