Support for my readability & continuous improvement soapboxes

[Art Kendall-2]

While going through some old notes I came across these quotes.

Programming can be fun, so can cryptography; however they should not be
combined.

        Kreitzberg and Shneiderman

Let us change our traditional attitude to the construction of programs.
Instead of imagining that our main task is to instruct a computer what
to do, let us concentrate rather on explaining to human beings what we
want a computer to do.

        Donald Knuth

Good code is its own best documentation. As you're about to add a
comment, ask yourself, 'How can I improve the code so that this comment
isn't needed?' Improve the code and then document it to make it even
clearer.

    Steve McConnell Code Complete

Plan to throw one [draft] away, you will anyhow.

    Fred Brooks


    Art Kendall
    Social Research Consultants

[Richard Ristow]

At 08:28 AM 1/12/2007, Art Kendall wrote:

>While going through some old notes I came across these quotes.
>
>Programming can be fun, so can cryptography; however they should not
>be combined.
>
>        Kreitzberg and Shneiderman

Two more, for which unfortunately I don't have attributions:

"There does not now exist, and never will, a language in which it is
the least bit difficult to write bad programs."

"More programming sins have been committed in the name of efficiency -
without necessarily achieving it - than from any other cause, including
simple stupidity."

And one of my own: "Let my write a nation's data structures, and I care
not who writes its code."

>Let us change our traditional attitude to the construction of
>programs. Instead of imagining that our main task is to instruct a
>computer what to do, let us concentrate rather on explaining to human
>beings what we want a computer to do.
>
>        Donald Knuth

That is right (fortunately, I don't have to contradict Knuth), but I'd
state it differently. It's not explaining it to human beings, though
that's a very good exercise; it's designing what's to be done. That
means, describing how the desired outcome relates to the starting data
or whatever; and how to get from one to the other, in steps that
translate naturally into whatever computational tool you have. (My
concurrent posting "Re: Graduate course on SPSS" speaks to similar
issues.)

>Good code is its own best documentation. As you're about to add a
>comment, ask yourself, 'How can I improve the code so that this
>comment isn't needed?' Improve the code and then document it to make
>it even clearer.
>
>    Steve McConnell Code Complete

I see the point, but I don't quite agree. (You can see by my postings
that I comment heavily.)

I start writing a program by putting in comments: date, purpose,
description of inputs and outputs. Including for SPSSX-L postings. I
don't include this in what I post, but the code usually begins like
this:


*  C:\Documents and Settings\Richard\My Documents                .
*    \Technical\spssx-l\Z-2006d                                  .
*    \2006-12-14 Sherman - How to convert base 10 into base 2.SPS.

*  In response to posting                                .
*  Date:         Thu, 14 Dec 2006 15:32:28 -0500         .
*  Reply-To:     Martin Sherman <[hidden email]>    .
*  Subject:      How to convert base 10 into base 2      .
*  To: [hidden email]                          .


And while you shouldn't have to explain what your code is doing (though
sometimes there's reason to do something 'cute' that may not be clear
later), there's often reason to explain why it's doing it, or what it
means:


*  This converts numbers representable with up to 5.
*  binary digits; i.e., 0-63. It may easily be     .
*  extended.                                       .


That especially goes for declaring variables;  very commonly, there
should be comments giving what they're for:


STRING  RespBnry   (A8) /* Binary representation of
                         /* "RESPONSES".
NUMERIC #BinPlce   (F2) /* N, for binary digit (2**n)
        /#BinDigt   (F1) /* Value (0/1) of binary digit
        /#Analyze   (F3) /* Remaining part of number   */.
STRING  #BinChar   (A1) /* Character rep. of #BinDigt */.


Or to make clear what you're doing; and, if it's odd, that you intended
it:


.  COMPUTE #BinDigt = MOD(#Analyze,2).
*  Binary digits:                .
*  1 is represented as '1'.      .
*  0 is represented as 'o'.      .
.  RECODE  #BinDigt
       (0    = 'o')
       (1    = '1')
       (ELSE = '?') INTO #BinChar.


>Plan to throw one [draft] away, you will anyhow.
>
>    Fred Brooks

Alas, you often won't. Even when you badly need to.

-Regards to all,
  Richard

[Bob Schacht-3]

At 02:37 PM 1/12/2007, Richard Ristow wrote:

>At 08:28 AM 1/12/2007, Art Kendall wrote:
>
>>While going through some old notes I came across these quotes.
>>
>>Programming can be fun, so can cryptography; however they should not
>>be combined.
>>
>>        Kreitzberg and Shneiderman
>
>Two more, for which unfortunately I don't have attributions:
>
>"There does not now exist, and never will, a language in which it is
>the least bit difficult to write bad programs." . .  .

May I join the fun? Here's some loose change:

While an undergraduate at the University of Wisconsin decades ago, I
majored in both Math and Anthropology-- two separate but simultaneous
majors. I was also a computer programmer. The thinking skills that were
required were very different. SPSS is, of course, a natural bridge between
statistics and computer science, on one hand, and a social science such as
Anthropology on the other hand.

What I found most helpful in Math and Statistics of any sort-- as well as
in computer programming-- is logical rigor of a kind seldom encountered in
the Social Sciences (there are competing attempts to explain this
difference). Most people on this planet are not prepared for the kind of
logical rigor required in Mathematics and Statistics.

For logical precision, Geometry and algebra in high school are good
preparation for computer programming.
But social science provides interesting examples of studies that can help
people see what all that logical rigor can do.

Of course students should also learn what "testing a hypothesis" means,
including using the terms correctly, and knowing the difference between the
hypothetico-deductive method, and exploratory data analysis. And when to
use them.

It is also very instructive to serve at the "Help desk" of a university's
computer services department. There, you get a chance to see many poorly
constructed research plans and people trying to implement them without the
foggiest notion of what they're doing. As a programmer, we were always
striving to write "User-proof" code, and were always amazed at the ways
people could think of to sabotage their own work (without intending to, of
course).

For a graduate course? a variety of experiences would be helpful, I think.
    * Spend some time with some actual programming code, writing a logical
flow chart of how it works.
    * Write a simple statistical computer program  that will read in data,
perform a few simple calculations, be guided by a few simple user-supplied
options, and print out the results. Get 3 classmates to use your program to
get some results that interest them. And write a report on what you did and
how it worked (or didn't!)
    * Volunteer time at a computer help desk, and keep a log of your
experiences.
    * Use an online database to test a hypothesis.
    * Demonstrate proficiency and understanding of
        * testing to see if a distribution is "normal";
        * testing a bivariate relationship;
        * testing a multivariate relationship.

That's all just loose change, and not to be confused with an actual
graduate course.

Bob in HI

Robert M. Schacht, Ph.D. <[hidden email]>
Pacific Basin Rehabilitation Research & Training Center
1268 Young Street, Suite #204
Research Center, University of Hawaii
Honolulu, HI 96814

[Art Kendall-2]

Richard Ristow wrote:

> At 08:28 AM 1/12/2007, Art Kendall wrote:
>
>> While going through some old notes I came across these quotes.
>>
>
>
> <snip>
>
>> Let us change our traditional attitude to the construction of
>> programs. Instead of imagining that our main task is to instruct a
>> computer what to do, let us concentrate rather on explaining to human
>> beings what we want a computer to do.
>>
>>        Donald Knuth
>
>
> That is right (fortunately, I don't have to contradict Knuth), but I'd
> state it differently. It's not explaining it to human beings, though
> that's a very good exercise; it's designing what's to be done. That
> means, describing how the desired outcome relates to the starting data
> or whatever; and how to get from one to the other, in steps that
> translate naturally into whatever computational tool you have. (My
> concurrent posting "Re: Graduate course on SPSS" speaks to similar
> issues.)

The human being it is most important to do this for is the user
her/himself.

>
>> Good code is its own best documentation. As you're about to add a
>> comment, ask yourself, 'How can I improve the code so that this
>> comment isn't needed?' Improve the code and then document it to make
>> it even clearer.
>>
>>    Steve McConnell Code Complete
>
>
> I see the point, but I don't quite agree. (You can see by my postings
> that I comment heavily.)

I notice that you seem to follow both parts of McConnells advice. You do
use variable names such as RespBnry and #BinPlce in the example below
rather than v1 and #v1.  You also have the additional comments.

I tend to to the same thing in a slightly different manner.
STRING  RespBnry   (A8) .
var label 'Binary representation of  "RESPONSES"'.

One QA step I require in studies is complete filling out of the variable
view. Doing it in syntax sometimes accomplishes documentation for the
syntax itself as well as completing the data view for documenting output.

>
> I start writing a program by putting in comments: date, purpose,
> description of inputs and outputs. Including for SPSSX-L postings. I
> don't include this in what I post, but the code usually begins like
> this:
>
>
> *  C:\Documents and Settings\Richard\My Documents                .
> *    \Technical\spssx-l\Z-2006d                                  .
> *    \2006-12-14 Sherman - How to convert base 10 into base 2.SPS.
>
> *  In response to posting                                .
> *  Date:         Thu, 14 Dec 2006 15:32:28 -0500         .
> *  Reply-To:     Martin Sherman <[hidden email]>    .
> *  Subject:      How to convert base 10 into base 2      .
> *  To: [hidden email]                          .
>
>
> <snip>                                .
>
>
> That especially goes for declaring variables;  very commonly, there
> should be comments giving what they're for:
>
>
> STRING  RespBnry   (A8) /* Binary representation of
>                         /* "RESPONSES".
> NUMERIC #BinPlce   (F2) /* N, for binary digit (2**n)
>        /#BinDigt   (F1) /* Value (0/1) of binary digit
>        /#Analyze   (F3) /* Remaining part of number   */.
> STRING  #BinChar   (A1) /* Character rep. of #BinDigt */.
>
> <snip>

[Richard Ristow]

At 07:37 PM 1/12/2007, I wrote:

>Two more [maxims], for which unfortunately I don't have attributions:

"No attributions" meant insufficient use of Google. (I'm not citing the
sites where I found the citations. That would be out of sight.)

>"There does not now exist, and never will, a language in which it is
>the least bit difficult to write bad programs."

Flon's Axiom: There does not now, nor will there ever, exist a
programming language in which it is the least bit hard to write bad
programs.

-Flon, Lawrence. "On Research in Structured Programming", [ACM] SIGPLAN
Notices, October 1975, Vol. 10 No. 10.

>"More programming sins have been committed in the name of efficiency -
>without necessarily achieving it - than from any other cause,
>including
>simple stupidity."

More computing sins are committed in the name of efficiency (without
necessarily achieving it) than for any other single reason - including
blind stupidity.

- Wulf, W. A. "A Case Against the GOTO," Proceedings of the 25th
National ACM Conference, August 1972, pp. 791-97.



>And one of my own: "Let me write a nation's data structures, and I
>care
>not who writes its code."