Date: Fri, 12 Jan 2007 19:37:42 -0500
Reply-To: Richard Ristow <wrristow@mindspring.com>
Sender: "SPSSX(r) Discussion" <SPSSX-L@LISTSERV.UGA.EDU>
From: Richard Ristow <wrristow@mindspring.com>
Subject: Re: Support for my readability & continuous improvement soapboxes
In-Reply-To: <45A78D00.1030801@verizon.net>
Content-Type: text/plain; charset="us-ascii"; format=flowed
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 <MSherman@LOYOLA.EDU> .
* Subject: How to convert base 10 into base 2 .
* To: SPSSX-L@LISTSERV.UGA.EDU .
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
