I think a large part of the problem is that kids are not taught to think. There was a classic Far Side cartoon many years ago called "Billy's Nightmare" or similar, where the little guy is in a library where every book is called "The big book of story problems", "The story problem anthology", "Advanced story problems", and so forth. Translating a problem to code, or code to a narrative just seems to be beyond the capabilities of many people.
I agree wholeheartedly with John Bodoh's recommendations - a flower box with an overall description of what this section is doing, and a running commentary in the remarks columns, at a more detailed level.
I disagree with John Gilmore's assertion that "coding police" do more harm than good - we have strict coding standards and a code quality inspector who has probably the worst job in the department, but makes sure that all code conforms.
David de Jongh
On Feb 10, 2012, at 08:58, Kirk Talman wrote:
> IBM Mainframe Assembler List <ASSEMBLER-LIST@LISTSERV.UGA.EDU> wrote on
> 02/10/2012 10:46:35 AM:
>
>> From: Michael Stack <li...@kcats.org>
>>
>> And I learned at an early age to look at the object code. This rule
>> was hammered home when we purchased commercial software which
>> contained such oddities as
>>
>> R3 EQU 5
>
> good point! bad EQUs are worse than bad comments, esp when reading code
> involved in sev 1 incident
>
And I once saw some code that contained such as:
ASIZE EQU 24 Array size
OK. Parameterized, possibly to allow future modification,
which I had to do, including changing the ASIZE EQU. Then
I found in multiple places such as:
LA R2,ASIZE(,R2) Add 24
... the comments defeated the modularity/modifiability
of the code. I can envision how it took two programmers
in succession to do this.
The same program also contained:
FIFTYSIX EQU 56 Data bytes in a TXT record
I suppose the coding standards required EQUates for all self-defining
terms.
-- gil
> IBM Mainframe Assembler List <ASSEMBLER-LIST@LISTSERV.UGA.EDU> wrote on
> 02/10/2012 10:46:35 AM:
>
>> From: Michael Stack <li...@kcats.org>
>>
>> And I learned at an early age to look at the object code. This rule
>> was hammered home when we purchased commercial software which
>> contained such oddities as
>>
>> R3 EQU 5
>
> good point! bad EQUs are worse than bad comments, esp when reading code
> involved in sev 1 incident
>
And I once saw some code that contained such as:
ASIZE EQU 24 Array size
OK. Parameterized, possibly to allow future modification,
which I had to do, including changing the ASIZE EQU. Then
I found in multiple places such as:
LA R2,ASIZE(,R2) Add 24
... the comments defeated the modularity/modifiability
of the code. I can envision how it took two programmers
in succession to do this.
The same program also contained:
FIFTYSIX EQU 56 Data bytes in a TXT record
I suppose the coding standards required EQUates for all self-defining
terms.
-- gil
