date:20120216

Re: code comments and code maintainability

2012-02-16 Thread Dave Cole


Sorry to be late to the party. (I was vacationing in Vegas. Great show town!)






A decade or two ago, I had a friend who didn't like to comment his
code. When asked to, he would say "It was hard to write. Therefore,
it should be hard to read!" That is a sentiment I have come to revile.






John Gilmore wrote:

A comment like 'store registers' attached to an SR instruction is
worse than useless.


Bernd Oppolzer wrote:

My favourite one is:
   BALR R3,0 SUBTRACT 1 FROM R3
Obviously, the opcode is wrong, should be BCTR.


I really laughed out loud when I saw these. Contrary to the first
poster's thesis, they both illustrate *perfectly* why even trivial
comments are useful!






WRT whether one should read the comments or the code (or even the
object), it is ridiculous to read one and not the others. When desk
checking, all three are important sources of information. To ignore
one in favor of the others is a sign of laziness and is always a
mistake. For example, when a comment contradicts the code, that is an
important red flag that would be missed by anyone focusing only on
the comments or only on the code.






At 2/10/2012 08:52 AM, John Gilmore wrote:

Comments are or, better, should be of two sorts:

1) Substantial prefixed blocks of text, often several hundred lines
of them, that describe what will be done and how it will be done,
and explicate coding conventions for parameters, and

2) comments following single instructions, 'remarks'.


I wholeheartedly agree with the general ideas here. These are the
elements of good quality commenting, and good quality commenting is
*essential* for writing good quality (and therefore maintainable) code.

Several years ago I gave a paper at SHARE about this. It was titled
"Considerate Programming: Reducing the Maintenance Costs of
Commercial Quality Code". If you are interested, you can find it
here:
http://www.colesoft.com/Articles/commercialqualityprogramming.pdf







Dave Cole  REPLY TO: dbc...@colesoft.com
ColeSoft Marketing WEB PAGE: http://www.colesoft.com
736 Fox Hollow RoadVOICE:540-456-8536
Afton, VA 22920FAX:  540-456-6658

Intentional abends: System vs. User vs. #DIE (was VarIabLe DD names in VSAM)

2012-02-16 Thread Dave Cole


Thanks for the mention Rob.


WRT this religions war over whether to use system abends vs. user
abends, I'm agnostic. My own personal preference is to use a
contrived 0C1 (which is what my dead traps are that Rob mentioned),
but it ain't worth a hill of beans to argue about.

However, not that my #DIE macro has been mentioned, I would like to add this.

One minor convenience of #DIE, in addition to those mentioned by
RScott, is that it can generate a conditional branch ahead of the
X'00DEAD' code, thereby making execution of the "dead trap" optional. Example:
LTR  R1,R1
#DIE NP,'ILLOGICAL IF R1 IS NOT POSITIVE'

z/XDC's internal code has *thousands* of #DIE traps scattered
throughout its logic. Yet, problem reports resulting from those traps
occur only a couple of times a year.

The purpose of the #DIE traps is to arrest illogical conditions
before that can seed a failure that occurs a million instructions
later. They are used within z/XDC's logic where the perceived
likelihood of the illogical condition is low or "nonexistent". i.e.
in places where it is not worth the effort to write a more polite handler.

The result of my use of #DIE traps is that when an "impossible"
condition does arise, my having trapped it early makes creating a fix
considerably easier. Sometimes I can produce and publish a fix within
only a day or two or sometimes even within an hour or two!




One good application for dead traps is to verify the critical details
of an interface to some outside support routine (especially
undocumented interfaces). If an API changes in an unexpected way, it
generally is good to know about that sooner than later.

One example of where I got bit by that is with IBM's TPUT service. A
couple of decades ago, they added some new return codes. I was using
a branch vector to react to the various return codes, so the new one
caused execution to blow past the vector entirely. There were several
lessons learned from that. One was to use dead traps to vcheck what
was returned.


The #DIE macro is available to anyone for free in a MACLIB.ZIP file
located at
http://www.colesoft.com/Downloads/downloads_utilities.html




Dave Cole  REPLY TO: dbc...@colesoft.com
ColeSoft Marketing WEB PAGE: http://www.colesoft.com
736 Fox Hollow RoadVOICE:540-456-8536
Afton, VA 22920FAX:  540-456-6658




At 2/13/2012 06:32 AM, Rob Scott wrote:

I have always liked Dave Cole's approach in z/XDC here - he supplies
a "#DIE" macro that places X'00DEAD' in the code followed by
identification bytes that indicate where in the code the #DIE was
and optional comments



Rob Scott
Lead Developer
Rocket Software
275 Grove Street * Newton, MA 02466-2272 * USA
Tel: +1.781.684.2305
Email: rsc...@rs.com
Web: www.rocketsoftware.com

-Original Message-

From: IBM Mainframe Assembler List
[mailto:ASSEMBLER-LIST@LISTSERV.UGA.EDU] On Behalf Of Martin Truebner
Sent: 13 February 2012 11:21
To: ASSEMBLER-LIST@LISTSERV.UGA.EDU
Subject: Re: VarIabLe DD names in VSAM

Thomas (or should I say "amateur in asm" ;-)

The idea is to produce something that is easy recognisable as "done
on purpose" and not to muddy the water more for this "unexpected"
situation.

I for example always have a EX *,* (or an equivalent if there is no
base covering it) after a EXEC CICS RETURN.

It must work- but hey, I have seen horses dying in front of
drugstores (German saying)

--
Martin

Pi_cap_CPU - all you ever need around MWLC/SCRT/CMT in z/VSE more
at http://www.picapcpu.de

alternatives

2012-02-16 Thread Ron Wells

 Looking for alternatives to CHANGEMAN any suggestions to Look at..??
 Pro's/Con's

--
Email Disclaimer
This  E-mail  contains  confidential  information  belonging to the sender, 
which  may be legally privileged information.  This information is intended 
only  for  the use of the individual or entity addressed above.  If you are not 
 the  intended  recipient, or  an  employee  or  agent responsible for 
delivering it to the intended recipient, you are hereby notified that any 
disclosure,  copying, distribution, or the taking of any action in reliance on 
the contents of the E-mail or attached files is strictly prohibited.

Re: alternatives

2012-02-16 Thread Hobart Spitz

Just my two cents:

Preface:  A change control/configuration management system usually
automates existing policies and procedures for software deployment.  They
tend to vary wildly from installation to installation.  Off the shelf
products have difficulty handling all the specific needs of a
particular site:  Cost-effective compromises have to be made.

My experiences:  I have been in five sites where they wrote their own
systems.  In all cases, the results were satisfactory,
full-functioned, right-sized, cost-effective and still in use last I
heard.  In two cases, I participated in the initial design, implementation,
and on-going support; in two others, in enhancement, maintenance and
support.  At one site, it took the team 1 day to define the requirements
and design the command-level interface, a second day to code the core
functions, and a week to implement the basic
web-based developer interface.  Subsequent enhancement, support and
maintenance took about a staff-week per year.

Conclusions:

   - Consider the costs and benefits of designing and writing your own
   change control/configuration management system.
   - Use an open ended design, with a command line accessible core.
   - Use a release methodology (per Gartner Group and my experiences):
   Piecemeal (AKA emergency) deployments mean untested configurations in
   production .

YMMV

On Thu, Feb 16, 2012 at 12:53 PM, Ron Wells  wrote:

>  Looking for alternatives to CHANGEMAN any suggestions to Look at..??
>  Pro's/Con's
>
> --
> Email Disclaimer
> This  E-mail  contains  confidential  information  belonging to the
> sender, which  may be legally privileged information.  This information is
> intended only  for  the use of the individual or entity addressed above.
>  If you are not  the  intended  recipient, or  an  employee  or  agent
> responsible for delivering it to the intended recipient, you are hereby
> notified that any disclosure,  copying, distribution, or the taking of any
> action in reliance on the contents of the E-mail or attached files is
> strictly prohibited.
>
>

--
OREXXMan

Re: code comments and code maintainability

2012-02-16 Thread Bill Fairchild

I try very hard to put a cogent comment on each machine instruction and all 
USINGs and DROPs.  And I add a paragraph or two at the beginning of small 
subroutines.  I do this for two reasons:  (1) I have spent a lot of time 
studying other people's code with either poor or no comments, and I don't want 
to inflict that misery on anyone else; (2)  but I especially don't want to 
inflict the misery on myself, either, and I know from experience that within a 
month or two I will not remember why I coded certain things the way I did, and 
the comments help ME understand my own code, too.   That's what enlightened 
self-interest is all about.

Bill Fairchild

-Original Message-
From: IBM Mainframe Assembler List [mailto:ASSEMBLER-LIST@LISTSERV.UGA.EDU] On 
Behalf Of Dave Cole
Sent: Thursday, February 16, 2012 4:07 AM
To: ASSEMBLER-LIST@LISTSERV.UGA.EDU
Subject: Re: code comments and code maintainability

Sorry to be late to the party. (I was vacationing in Vegas. Great show town!)

A decade or two ago, I had a friend who didn't like to comment his code. When 
asked to, he would say "It was hard to write. Therefore, it should be hard to 
read!" That is a sentiment I have come to revile.

John Gilmore wrote:
>A comment like 'store registers' attached to an SR instruction is worse
>than useless.

Bernd Oppolzer wrote:
>My favourite one is:
>BALR R3,0 SUBTRACT 1 FROM R3
>Obviously, the opcode is wrong, should be BCTR.

I really laughed out loud when I saw these. Contrary to the first poster's 
thesis, they both illustrate *perfectly* why even trivial comments are useful!

WRT whether one should read the comments or the code (or even the object), it 
is ridiculous to read one and not the others. When desk checking, all three are 
important sources of information. To ignore one in favor of the others is a 
sign of laziness and is always a mistake. For example, when a comment 
contradicts the code, that is an important red flag that would be missed by 
anyone focusing only on the comments or only on the code.

At 2/10/2012 08:52 AM, John Gilmore wrote:
>Comments are or, better, should be of two sorts:
>
>1) Substantial prefixed blocks of text, often several hundred lines of
>them, that describe what will be done and how it will be done, and
>explicate coding conventions for parameters, and
>
>2) comments following single instructions, 'remarks'.

I wholeheartedly agree with the general ideas here. These are the elements of 
good quality commenting, and good quality commenting is
*essential* for writing good quality (and therefore maintainable) code.

Several years ago I gave a paper at SHARE about this. It was titled 
"Considerate Programming: Reducing the Maintenance Costs of Commercial Quality 
Code". If you are interested, you can find it
here:
http://www.colesoft.com/Articles/commercialqualityprogramming.pdf

Dave Cole  REPLY TO: dbc...@colesoft.com
ColeSoft Marketing WEB PAGE: http://www.colesoft.com
736 Fox Hollow RoadVOICE:540-456-8536
Afton, VA 22920FAX:  540-456-6658

Re: code comments and code maintainability

2012-02-16 Thread Chris Craddock

Bill writes:> 
> I try very hard to put a cogent comment on each machine instruction and all 
> USINGs and DROPs.  And I add a paragraph or two at the beginning of small 
> subroutines.  I do this for two reasons:  (1) I have spent a lot of time 
> studying other people's code with either poor or no comments, and I don't 
> want to inflict that misery on anyone else; (2)  but I especially don't want 
> to inflict the misery on myself, either, and I know from experience that 
> within a month or two I will not remember why I coded certain things the way 
> I did, and the comments help ME understand my own code, too.   That's what 
> enlightened self-interest is all about.


AMEN!!

Re: code comments and code maintainability

2012-02-16 Thread Kirk Talman

IBM Mainframe Assembler List  wrote on
02/16/2012 03:41:28 PM:

> From: Chris Craddock 

> Bill writes:>
> > I try very hard to put a cogent comment on each machine
> instruction and all USINGs and DROPs.  And I add a paragraph or two
> at the beginning of small subroutines.  I do this for two reasons:
> (1) I have spent a lot of time studying other people's code with
> either poor or no comments, and I don't want to inflict that misery
> on anyone else; (2)  but I especially don't want to inflict the
> misery on myself, either, and I know from experience that within a
> month or two I will not remember why I coded certain things the way
> I did, and the comments help ME understand my own code, too.
> That's what enlightened self-interest is all about.

> AMEN!!

DITTO!!

-
The information contained in this communication (including any
attachments hereto) is confidential and is intended solely for the
personal and confidential use of the individual or entity to whom
it is addressed. If the reader of this message is not the intended
recipient or an agent responsible for delivering it to the intended
recipient, you are hereby notified that you have received this
communication in error and that any review, dissemination, copying,
or unauthorized use of this information, or the taking of any
action in reliance on the contents of this information is strictly
prohibited. If you have received this communication in error,
please notify us immediately by e-mail, and delete the original
message. Thank you

Re: code comments and code maintainability

2012-02-16 Thread Bodoh John Robert

I agree completely.  Why doesn't the rest of the world agree and adhere to this 
philosophy?

John

-Original Message-
From: IBM Mainframe Assembler List [mailto:ASSEMBLER-LIST@LISTSERV.UGA.EDU] On 
Behalf Of Bill Fairchild
Sent: Thursday, February 16, 2012 11:52 AM
To: ASSEMBLER-LIST@LISTSERV.UGA.EDU
Subject: Re: code comments and code maintainability

I try very hard to put a cogent comment on each machine instruction and all 
USINGs and DROPs.  And I add a paragraph or two at the beginning of small 
subroutines.  I do this for two reasons:  (1) I have spent a lot of time 
studying other people's code with either poor or no comments, and I don't want 
to inflict that misery on anyone else; (2)  but I especially don't want to 
inflict the misery on myself, either, and I know from experience that within a 
month or two I will not remember why I coded certain things the way I did, and 
the comments help ME understand my own code, too.   That's what enlightened 
self-interest is all about.

Bill Fairchild

-Original Message-
From: IBM Mainframe Assembler List [mailto:ASSEMBLER-LIST@LISTSERV.UGA.EDU] On 
Behalf Of Dave Cole
Sent: Thursday, February 16, 2012 4:07 AM
To: ASSEMBLER-LIST@LISTSERV.UGA.EDU
Subject: Re: code comments and code maintainability

Sorry to be late to the party. (I was vacationing in Vegas. Great show town!)

A decade or two ago, I had a friend who didn't like to comment his code. When 
asked to, he would say "It was hard to write. Therefore, it should be hard to 
read!" That is a sentiment I have come to revile.

John Gilmore wrote:
>A comment like 'store registers' attached to an SR instruction is worse
>than useless.

Bernd Oppolzer wrote:
>My favourite one is:
>BALR R3,0 SUBTRACT 1 FROM R3
>Obviously, the opcode is wrong, should be BCTR.

I really laughed out loud when I saw these. Contrary to the first poster's 
thesis, they both illustrate *perfectly* why even trivial comments are useful!

WRT whether one should read the comments or the code (or even the object), it 
is ridiculous to read one and not the others. When desk checking, all three are 
important sources of information. To ignore one in favor of the others is a 
sign of laziness and is always a mistake. For example, when a comment 
contradicts the code, that is an important red flag that would be missed by 
anyone focusing only on the comments or only on the code.

At 2/10/2012 08:52 AM, John Gilmore wrote:
>Comments are or, better, should be of two sorts:
>
>1) Substantial prefixed blocks of text, often several hundred lines of
>them, that describe what will be done and how it will be done, and
>explicate coding conventions for parameters, and
>
>2) comments following single instructions, 'remarks'.

I wholeheartedly agree with the general ideas here. These are the elements of 
good quality commenting, and good quality commenting is
*essential* for writing good quality (and therefore maintainable) code.

Several years ago I gave a paper at SHARE about this. It was titled 
"Considerate Programming: Reducing the Maintenance Costs of Commercial Quality 
Code". If you are interested, you can find it
here:
http://www.colesoft.com/Articles/commercialqualityprogramming.pdf

Dave Cole  REPLY TO: dbc...@colesoft.com
ColeSoft Marketing WEB PAGE: http://www.colesoft.com
736 Fox Hollow RoadVOICE:540-456-8536
Afton, VA 22920FAX:  540-456-6658

Re: code comments and code maintainability

2012-02-16 Thread Rob van der Heij

On Thu, Feb 16, 2012 at 11:02 PM, Bodoh John Robert
 wrote:
>
> I agree completely.  Why doesn't the rest of the world agree and adhere to 
> this philosophy?

I don't think the disagreement is about that. As stated, the goal is
to have *relevant* comments in the code. There's lots of reasons why
this does not happen in real life. Eg
 - copy and change code, forgetting the remarks
 - use of boiler plate comments that don't get updated
 - the code was obvious the first hour after you wrote it
 - testing may reveal coding errors, but not incorrect comments
 - those doing peer review, is code rejected due to wrong comments?

Having no comments is sometimes better than having wrong comments. In
many cases no comments is better than trivial ones. When it's there it
may disrupt the concentration needed to read the program (especially
with "funny" remarks).

The quoted BALR R3,0 is cute, but in my experience its often the opposite:

   LA R4,9  Set R4 with 9
or
   MVC ABCDATE,XYZDATE Copy date into ABC block
   ...
   MVC ABCTIME,XYZTIME Copy date into ABC block

Only careful study of the code (and update logging) will reveal
whether the code or remark is wrong (if any).

Somewhere in this thread I suggested that remarks should be about the
*why* rather than *what* of the instruction. Dave Cole's neat paper
shows mostly "why" remarks. From browsing my inheritance, I think most
repeated remarks (as written, not generated by macros) tend to be
*what* and my experience is that the *what* more often is invalidated
by code changes and bug fixes.

Rob

Re: code comments and code maintainability

Intentional abends: System vs. User vs. #DIE (was VarIabLe DD names in VSAM)

alternatives

Re: alternatives

Re: code comments and code maintainability

Re: code comments and code maintainability

Re: code comments and code maintainability

Re: code comments and code maintainability

Re: code comments and code maintainability

9 matches

Site Navigation

Mail list logo

Footer information