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

RE: [XP] Ob-literate programming

Expand Messages
  • Kent Beck
    ... Whenever I found myself trying to explain why a bit of code wasn t as clear as it could be, I found it was less work to go clean up the code first then
    Message 1 of 17 , Aug 1, 2005
    • 0 Attachment
      > -----Original Message-----
      > From: extremeprogramming@yahoogroups.com
      > [mailto:extremeprogramming@yahoogroups.com] On Behalf Of John Carter
      > Sent: Sunday, July 31, 2005 6:43 PM
      > To: extremeprogramming@yahoogroups.com
      > Subject: [XP] Ob-literate programming
      >
      > > It was easier to continue refining the code than it was to
      > try to explain
      > > why it wasn't clean.
      >
      > What are you saying? "Don't describe, clean?" Xor "Describe
      > to find what
      > you need to clean, clean, then carry on describing?"

      Whenever I found myself trying to explain why a bit of code wasn't as clear
      as it could be, I found it was less work to go clean up the code first then
      explain it. Ward and I wrote our first literate program to describe how the
      ScrollController worked. We thought the code was pretty clean until we
      started describing it. By the time we were done we had touched almost all of
      the original code.

      > > I also became aware of just how much there was to
      > > communicate when describing code.
      >
      > Were you simply describing the implementation, or writing the
      > requirement
      > spec, high level design, detailed design, use cases, program,
      > reference
      > manual and user guide etc. etc. in one document?

      Following Knuth's lead, I try to point out what I find interesting about a
      program. I try to write a coherent story, so a reader can follow the program
      end-to-end. Sometimes what is interesting is the design, or a clever use of
      the programming language, or a performance optimization, or the theory
      behind the program. I haven't ever incorporated a reference manual or user
      guide, though. Those seem to me to be directed at a different audience.

      Sincerely yours,

      Kent Beck
      Three Rivers Institute
    • Bill Rutiser
      ... Kent, Have you published or posted any examples of your literate programming? Bill Rutiser Gaithersburg, MD, US
      Message 2 of 17 , Aug 1, 2005
      • 0 Attachment
        Kent Beck wrote:

        >Following Knuth's lead, I try to point out what I find interesting about a
        >program. I try to write a coherent story, so a reader can follow the program
        >end-to-end. Sometimes what is interesting is the design, or a clever use of
        >the programming language, or a performance optimization, or the theory
        >behind the program. I haven't ever incorporated a reference manual or user
        >guide, though. Those seem to me to be directed at a different audience.
        >
        >Sincerely yours,
        >
        >Kent Beck
        >Three Rivers Institute
        >
        >
        Kent,

        Have you published or posted any examples of your literate programming?

        Bill Rutiser
        Gaithersburg, MD, US
      • Phlip
        ... The first line of a program should hook the computer, and make it care about the program --Dan Twedt -- Phlip http://www.c2.com/cgi/wiki?ZeekLand
        Message 3 of 17 , Aug 1, 2005
        • 0 Attachment
          John Carter wrote:

          > Most Amazing and Attention Getting Line should be first in a program,
          > told as a story.

          "The first line of a program should 'hook' the computer, and make it
          'care' about the program" --Dan Twedt

          --
          Phlip
          http://www.c2.com/cgi/wiki?ZeekLand
        • Kent Beck
          Bill, Kent Beck s Guide to Better Smalltalk (not my choice of title) is a collection of columns from the late, lamented Smalltalk Report. Many of them are
          Message 4 of 17 , Aug 4, 2005
          • 0 Attachment
            Bill,

            "Kent Beck's Guide to Better Smalltalk" (not my choice of title) is a
            collection of columns from the late, lamented Smalltalk Report. Many of them
            are literate programs.

            Sincerely yours,

            Kent Beck
            Three Rivers Institute

            > -----Original Message-----
            > From: extremeprogramming@yahoogroups.com
            > [mailto:extremeprogramming@yahoogroups.com] On Behalf Of Bill Rutiser
            > Sent: Monday, August 01, 2005 5:20 AM
            > To: extremeprogramming@yahoogroups.com
            > Subject: Re: [XP] Ob-literate programming
            >
            > Kent Beck wrote:
            >
            > >Following Knuth's lead, I try to point out what I find
            > interesting about a
            > >program. I try to write a coherent story, so a reader can
            > follow the program
            > >end-to-end. Sometimes what is interesting is the design, or
            > a clever use of
            > >the programming language, or a performance optimization, or
            > the theory
            > >behind the program. I haven't ever incorporated a reference
            > manual or user
            > >guide, though. Those seem to me to be directed at a
            > different audience.
            > >
            > >Sincerely yours,
            > >
            > >Kent Beck
            > >Three Rivers Institute
            > >
            > >
            > Kent,
            >
            > Have you published or posted any examples of your literate
            > programming?
            >
            > Bill Rutiser
            > Gaithersburg, MD, US
            >
            >
            >
            > 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.