Interesting Quote On Communication Via The Program

[Thomas Passin]

This paragraph caught my eye:

"One of the early experiences that led me to focus on communication was discovering Knuth's Literate Programming: a progam should read like a book. It should have plot, rhythm, and delightful little turns of phrase. When Ward Cunningham and I first read about literate programs, we decided to try it. We sat down with one of the cleanest pieces of code in the Smalltalk image, the ScrollController, and tried to make it into a story. Hours later we had completely rewritten the code on our way to a reasonable paper. Every time a bit of logic was a little hard to explain, it was easier to rewrite the code than explain why the code was hard to understand. The demands of communication changed our perspective on coding."

From Kent Beck. "A Theory of Programming". Dr. Dobb's Journal, November 2007

[Edward K. Ream]

On Mon, Oct 17, 2022 at 10:17 AM Thomas Passin <tbp1...@gmail.com> wrote:

This paragraph caught my eye:

"One of the early experiences that led me to focus on communication was discovering Knuth's Literate Programming: a progam should read like a book. It should have plot, rhythm, and delightful little turns of phrase. When Ward Cunningham and I first read about literate programs, we decided to try it. We sat down with one of the cleanest pieces of code in the Smalltalk image, the ScrollController, and tried to make it into a story. Hours later we had completely rewritten the code on our way to a reasonable paper. Every time a bit of logic was a little hard to explain, it was easier to rewrite the code than explain why the code was hard to understand. The demands of communication changed our perspective on coding."

Thanks for this. As you know, I have a different opinion. Rather than a novel, programs are more like a reference book. Narrative is great for a Theory of Operation. For everything else, not so much.

Edward

[Thomas Passin]

I think that the idea that code should be able to communicate its intent clearly and simply is a good goal.  I also think that there are times when an explanation in a judicious comment as to why it's being done this way, or what is to be accomplished, can be very helpful.

[Edward K. Ream]

On Mon, Oct 17, 2022 at 1:16 PM Thomas Passin <tbp1...@gmail.com> wrote:

I think that the idea that code should be able to communicate its intent clearly and simply is a good goal.  I also think that there are times when an explanation in a judicious comment as to why it's being done this way, or what is to be accomplished, can be very helpful.

Who could argue with that :-)

Edward

[Thomas Passin]

There seem to be some people who think that code can speak for itself and need no comments at all.  I am not one of them.

[Miles Fidelman]

Personally, I'm a big proponent of writing the documentation first.  Then filling it in with code.  Makes life a lot easier for all concerned - particularly those who have to deploy & maintain big systems.

Miles Fidelman

-- 
In theory, there is no difference between theory and practice.
In practice, there is.  .... Yogi Berra

Theory is when you know everything but nothing works. 
Practice is when everything works but no one knows why. 
In our lab, theory and practice are combined: 
nothing works and no one knows why.  ... unknown