Re: A Smile for the Week

[Howard Brazee]

On 6 Jan 2009 08:01:46 -0800, shmuel+ibm-m...@patriot.net (Shmuel Metz
, Seymour J.) wrote:

>> LAR1,13   Thirteen,
>
>When I last taught a programming class I explained that such comments
>would reduce their grades.
>
>> SLR   R0,R0   Multiply by one,
>
>An incorrect comment would reduce their grades even more :-(

An interesting case would be to have students debug a subtle bug.   Do
this later in the term weeks after talking about documentation.   But
grade them on fixing and/or enhancing the documentation that was
already in the program relevant to that bug.

--
For IBM-MAIN subscribe / signoff / archive access instructions,
send email to lists...@bama.ua.edu with the message: GET IBM-MAIN INFO
Search the archives at http://bama.ua.edu/archives/ibm-main.html

Re: A Smile for the Week

[Shmuel Metz (Seymour J.)]

In ,
on 01/05/2009
   at 07:32 AM, "Chase, John"  said:

> LAR1,13   Thirteen,

When I last taught a programming class I explained that such comments
would reduce their grades.

> SLR   R0,R0   Multiply by one,

An incorrect comment would reduce their grades even more :-(
 
-- 
 Shmuel (Seymour J.) Metz, SysProg and JOAT
 ISO position; see  
We don't care. We don't have to care, we're Congress.
(S877: The Shut up and Eat Your spam act of 2003)

--
For IBM-MAIN subscribe / signoff / archive access instructions,
send email to lists...@bama.ua.edu with the message: GET IBM-MAIN INFO
Search the archives at http://bama.ua.edu/archives/ibm-main.html

Re: A Smile for the Week

[Kirk Wolf]

IMO, the best exploration of "literate programming" and the like is
the "anti-pattern" - "How to write unmaintainable code" :

http://mindprod.com/jgloss/unmain.html

Kirk Wolf
Dovetailed Technologies

--
For IBM-MAIN subscribe / signoff / archive access instructions,
send email to lists...@bama.ua.edu with the message: GET IBM-MAIN INFO
Search the archives at http://bama.ua.edu/archives/ibm-main.html

Re: A Smile for the Week

[Howard Brazee]

On 5 Jan 2009 05:35:23 -0800, jch...@ussco.com (Chase, John) wrote:

>[label]  DS0H
> LAR1,13   Thirteen,
> SLR   R0,R0   Multiply by one,
> LTR   R1,R1   Still got thirteen,
> BZOOPSIE  But wasn't that fun?
> LAR1,13   Now take the same thirteen,
> SLA   R1,1Multiply by two,
> LTR   R1,R1   Twenty-six hours,
> BNZ   LATEThe train's overdue.
>
>(Apologies to the late Roger Miller.)  :-)

Now that's funny - because I've been there!

--
For IBM-MAIN subscribe / signoff / archive access instructions,
send email to lists...@bama.ua.edu with the message: GET IBM-MAIN INFO
Search the archives at http://bama.ua.edu/archives/ibm-main.html

Re: A Smile for the Week

[Chase, John]

> -Original Message-
> From: IBM Mainframe Discussion List On Behalf Of P S
> 
> [ snip ]
> 
> I worked for a development company where, at an engineering meeting,
> the VP of Engineering said that folks shouldn't comment their code,
> because the comments might not be correct.  I waited for him to laugh.
> He didn't.

[label]  DS0H
 LAR1,13   Thirteen,
 SLR   R0,R0   Multiply by one,
 LTR   R1,R1   Still got thirteen,
 BZOOPSIE  But wasn't that fun?
 LAR1,13   Now take the same thirteen,
 SLA   R1,1Multiply by two,
 LTR   R1,R1   Twenty-six hours,
 BNZ   LATEThe train's overdue.

(Apologies to the late Roger Miller.)  :-)

Of course, that ignores the possibility that the _code_ might not be
correct 

-jc-

--
For IBM-MAIN subscribe / signoff / archive access instructions,
send email to lists...@bama.ua.edu with the message: GET IBM-MAIN INFO
Search the archives at http://bama.ua.edu/archives/ibm-main.html

Re: A Smile for the Week

[P S]

Argh, key typo: "...they're NOW out of business..."!

On Sun, Jan 4, 2009 at 12:10 AM, P S  wrote:
> On Fri, Jan 2, 2009 at 3:04 PM, Eric Bielefeld  wrote:
>> I hope that when people say "Real Programmers don't comment code" that they
>> are being humorous, or just kidding around.  Assemble code for someone like
>> myself who has done a lot of coding, but done it a long time ago, is hard to
>> read.  Good comments make it at least possible to follow what the author was
>> doing.  I think if I were the boss, and someone wrote a lot of assmbler code
>> without comments, they would either change their ways, or find a different
>> job.
>
> I worked for a development company where, at an engineering meeting,
> the VP of Engineering said that folks shouldn't comment their code,
> because the comments might not be correct.  I waited for him to laugh.
> He didn't.
>
> Later, I asked one of the others about it; he assured me that the VP
> was serious.
>
> I ignored him.
>
> They're not out of business...
>
> (I know, it must have been MY fault!)
>

--
For IBM-MAIN subscribe / signoff / archive access instructions,
send email to lists...@bama.ua.edu with the message: GET IBM-MAIN INFO
Search the archives at http://bama.ua.edu/archives/ibm-main.html

Re: A Smile for the Week

[P S]

On Fri, Jan 2, 2009 at 3:04 PM, Eric Bielefeld  wrote:
> I hope that when people say "Real Programmers don't comment code" that they
> are being humorous, or just kidding around.  Assemble code for someone like
> myself who has done a lot of coding, but done it a long time ago, is hard to
> read.  Good comments make it at least possible to follow what the author was
> doing.  I think if I were the boss, and someone wrote a lot of assmbler code
> without comments, they would either change their ways, or find a different
> job.

I worked for a development company where, at an engineering meeting,
the VP of Engineering said that folks shouldn't comment their code,
because the comments might not be correct.  I waited for him to laugh.
He didn't.

Later, I asked one of the others about it; he assured me that the VP
was serious.

I ignored him.

They're not out of business...

(I know, it must have been MY fault!)

--
For IBM-MAIN subscribe / signoff / archive access instructions,
send email to lists...@bama.ua.edu with the message: GET IBM-MAIN INFO
Search the archives at http://bama.ua.edu/archives/ibm-main.html

Re: A Smile for the Week

[Shmuel Metz (Seymour J.)]

In , on 01/02/2009
   at 01:45 PM, Howard Brazee  said:

>Today's code should not be obtuse enough that other programmers have to
>study to find out what we did.   But sometimes they should know why we
>did it a particular way.   (Assembler needs more documentation than "self
>documenting" languages, but design the documentation so that it is read
>and maintained).

There are no self documenting languages. Regardless of the language, a
real programmer will use appropriate choices of comments and labels to
make the code legible, and will keep the documentation up to date.
Responsible management will not only allow him to do so, but will require
it. Anything less will come back to haunt you, or your successor.
 
-- 
 Shmuel (Seymour J.) Metz, SysProg and JOAT
 ISO position; see  
We don't care. We don't have to care, we're Congress.
(S877: The Shut up and Eat Your spam act of 2003)

--
For IBM-MAIN subscribe / signoff / archive access instructions,
send email to lists...@bama.ua.edu with the message: GET IBM-MAIN INFO
Search the archives at http://bama.ua.edu/archives/ibm-main.html

Re: A Smile for the Week

[Gerhard Postpischil]

Howard Brazee wrote:

I remember running a flow-chart program around 1980 that made
absolutely no sense to me.   Why have a program read a CoBOL program
and create a flow chart?   It's much easier to read the CoBOL program
itself.Documentation is useful in telling us what the program is
SUPPOSED to be doing, and why.  It should tell us who made business
decisions about the program.   It should explain data flow and impacts
outside of the job or dialog.


1) For non-programmers, it offers at least a small chance of 
understanding what a program is supposed to do, for instance, 
your boss's boss.


2) While reading the program, you have to flip back and forth 
between pages or screens, making it hard to build and maintain a 
good picture of what's going on; i.e., you get lost in the details.


But I'm biased, having written the output portion of ADR's 
Autoflow for the 709x.




Gerhard Postpischil
Bradford, VT

--
For IBM-MAIN subscribe / signoff / archive access instructions,
send email to lists...@bama.ua.edu with the message: GET IBM-MAIN INFO
Search the archives at http://bama.ua.edu/archives/ibm-main.html

Re: A Smile for the Week

[John McKown]

Instead of comments and flow charts and the like, let's just go with
"literate programming" ala Dr. Knuth.

http://www-cs-faculty.stanford.edu/~knuth/lp.html


Literate programming is a methodology that combines a programming language
with a documentation language, thereby making programs more robust, more
portable, more easily maintained, and arguably more fun to write than
programs that are written only in a high-level language. The main idea is to
treat a program as a piece of literature, addressed to human beings rather
than to a computer. The program is also viewed as a hypertext document,
rather like the World Wide Web. (Indeed, I used the word WEB for this
purpose long before CERN grabbed it!) This book is an anthology of essays
including my early papers on related topics such as structured programming,
as well as the article in The Computer Journal that launched Literate
Programming itself. The articles have been revised, extended, and brought up
to date. 


--
John

--
For IBM-MAIN subscribe / signoff / archive access instructions,
send email to lists...@bama.ua.edu with the message: GET IBM-MAIN INFO
Search the archives at http://bama.ua.edu/archives/ibm-main.html

Re: A Smile for the Week

[Howard Brazee]

On 2 Jan 2009 12:10:57 -0800, eric-ibmm...@wi.rr.com (Eric Bielefeld)
wrote:

>I hope that when people say "Real Programmers don't comment code" that they 
>are being humorous, or just kidding around.  Assemble code for someone like 
>myself who has done a lot of coding, but done it a long time ago, is hard to 
>read.  Good comments make it at least possible to follow what the author was 
>doing.  I think if I were the boss, and someone wrote a lot of assmbler code 
>without comments, they would either change their ways, or find a different 
>job.

I believe we all are kidding.   That said, unreliable documentation
can be dangerous, and in my experience, documentation rarely gets
updated adequately over time.

I remember running a flow-chart program around 1980 that made
absolutely no sense to me.   Why have a program read a CoBOL program
and create a flow chart?   It's much easier to read the CoBOL program
itself.Documentation is useful in telling us what the program is
SUPPOSED to be doing, and why.  It should tell us who made business
decisions about the program.   It should explain data flow and impacts
outside of the job or dialog.

Today's code should not be obtuse enough that other programmers have
to study to find out what we did.   But sometimes they should know why
we did it a particular way.   (Assembler needs more documentation than
"self documenting" languages, but design the documentation so that it
is read and maintained).

--
For IBM-MAIN subscribe / signoff / archive access instructions,
send email to lists...@bama.ua.edu with the message: GET IBM-MAIN INFO
Search the archives at http://bama.ua.edu/archives/ibm-main.html

Re: A Smile for the Week

[Eric Bielefeld]

I hope that when people say "Real Programmers don't comment code" that they 
are being humorous, or just kidding around.  Assemble code for someone like 
myself who has done a lot of coding, but done it a long time ago, is hard to 
read.  Good comments make it at least possible to follow what the author was 
doing.  I think if I were the boss, and someone wrote a lot of assmbler code 
without comments, they would either change their ways, or find a different 
job.


As to the comment I quoted below, if the code works, or does what it is 
supposed to, it can't be all bad.


Eric Bielefeld

- Original Message - 
From: "Thomas Berg" 

Newsgroups: bit.listserv.ibm-main
To: 
Sent: Friday, January 02, 2009 9:00 AM
Subject: SV: A Smile for the Week



If You comment Your code You disclose how
smart - or dumb - the thoughts behind the
coding was.  If there were any...

There could the reason for omitting comments
hide... ;)




Regards,
Thomas Berg
__
Thomas Berg   Specialist   IT-U   SWEDBANK 


--
For IBM-MAIN subscribe / signoff / archive access instructions,
send email to lists...@bama.ua.edu with the message: GET IBM-MAIN INFO
Search the archives at http://bama.ua.edu/archives/ibm-main.html

Re: A Smile for the Week

[Roberto Halais]

Interesting link

http://www.cfug-md.org/articles/progcreed.cfm

On Fri, Jan 2, 2009 at 10:33 AM, Howard Brazee wrote:

> On 1 Jan 2009 17:25:30 -0800, eamacn...@yahoo.ca (Ted MacNEIL) wrote:
>
> >A TRUE programmer does not comment their code!
> >It was hard to write; it should be hard to read!
>
>
> (We don't want others to know that it really wasn't hard to write).
> But if we had to analyze what the users wanted - they should analyze
> what we wanted!
>
> --
> For IBM-MAIN subscribe / signoff / archive access instructions,
> send email to lists...@bama.ua.edu with the message: GET IBM-MAIN INFO
> Search the archives at http://bama.ua.edu/archives/ibm-main.html
>



-- 
"I am as you, in you, for you. One as you in all, as all, forever. My call
is your call."

--
For IBM-MAIN subscribe / signoff / archive access instructions,
send email to lists...@bama.ua.edu with the message: GET IBM-MAIN INFO
Search the archives at http://bama.ua.edu/archives/ibm-main.html

Re: A Smile for the Week

[Howard Brazee]

On 1 Jan 2009 17:25:30 -0800, eamacn...@yahoo.ca (Ted MacNEIL) wrote:

>A TRUE programmer does not comment their code!
>It was hard to write; it should be hard to read!


(We don't want others to know that it really wasn't hard to write).
But if we had to analyze what the users wanted - they should analyze
what we wanted!

--
For IBM-MAIN subscribe / signoff / archive access instructions,
send email to lists...@bama.ua.edu with the message: GET IBM-MAIN INFO
Search the archives at http://bama.ua.edu/archives/ibm-main.html

Re: A Smile for the Week

[Ted MacNEIL]

>4) "A TRUE Klingon Warrior does not comment his code!"

A TRUE programmer does not comment their code!
It was hard to write; it should be hard to read!
-
Too busy driving to stop for gas!

--
For IBM-MAIN subscribe / signoff / archive access instructions,
send email to lists...@bama.ua.edu with the message: GET IBM-MAIN INFO
Search the archives at http://bama.ua.edu/archives/ibm-main.html

Re: A Smile for the Week

[Ted MacNEIL]

>4) "A TRUE Klingon Warrior does not comment his code!"

No programmer should comment code!
It was hard to write -- it should be hard to read!

-
Too busy driving to stop for gas!

--
For IBM-MAIN subscribe / signoff / archive access instructions,
send email to lists...@bama.ua.edu with the message: GET IBM-MAIN INFO
Search the archives at http://bama.ua.edu/archives/ibm-main.html