I once got hassled for using a decision table to document something for which a flow chart would have been a mare's nest. Later, it was fun getting a data-driven program past an agency that had never seen one before. Fortunately, in both cases sanity prevailed.
That said, copious comments *about the code* help. E.g., don't explain what an UNPK instruction does, but explain that you've offset a translation table by -240 because of the inserted F zones. -- Shmuel (Seymour J.) Metz http://mason.gmu.edu/~smetz3 ________________________________________ From: IBM Mainframe Discussion List [[email protected]] on behalf of Bob Bridges [[email protected]] Sent: Friday, June 18, 2021 11:53 AM To: [email protected] Subject: Re: EXTERNAL: Coding for the future Tom, I wondered whether someone would point that out. I've never written in IBM assembler, so yeah, such a comment might help me if I have to figure out what an exit does. But I remember as a COBOL programmer suffering under a restriction at a prior employer: Although it wasn't in the Official Coding Standards, the review teams always disallowed STRING and UNSTRING commands because "there will be some programmers who aren't familiar with them". My reaction at the time was that they're COBOL programmers; it's their job to learn the language. My next boss (at another company) agreed; a COBOL programmer should know COBOL, and if he doesn't, no shame, but learn it, that's all. I guess that sounds like I'm siding with Shmuel on this. Well, yeah, I guess I am. --- Bob Bridges, [email protected], cell 336 382-7313 /* In the search for virtue there are many roads. There are some who walk in procession, beating their bare backs with whips; others go into the desert and starve until their totem animal appears to them; some sit in darkened auditoria while the entire Ring Cycle plays; but best of all is to go to sea. [email protected] */ -----Original Message----- From: IBM Mainframe Discussion List <[email protected]> On Behalf Of Savor, Thomas Sent: Wednesday, June 16, 2021 12:49 ==> LA R7,5 Put 5 in register 7 It depends on the intended target audience. Now I and you know that a 5 is put in Register 7, but many shops have only a couple Assembler Programmers....but many more Cobol programmers. Telling "them" that a 5 is put in Register 7 can be helpful to solving a problem or learning what a program does. Way too many Cobol programmers that I run into are scared of looking at Assembler...like just looking at it or trying to learn it is going to give you Ebola...so even very basic instructions can be helpful...especially if Instruction says LA 7,5 then it really helps "them". -----Original Message----- From: IBM Mainframe Discussion List <[email protected]> On Behalf Of Seymour J Metz Sent: Wednesday, June 16, 2021 11:58 AM Long ago in a galaxy far away, they handed each of us a stack of manuals and told use that we were all enrolled in a 7070 class and had to read all of the manuals before the class started. It turned out that some of the students were answering questions that stumped the instructor, and that if you read the manuals you didn't need the course. The worst are the ones that score based on the quantity of comments instead of their quality. That guaranties cluttered and unhelpful comments. People will behave in such a fashion as to optimize how their organization ranks them; if teir grades or performance reviews depend on doing something sub-optimal, then that's what they'll do. Measure the things that actually matter. I generally frown on marking students down on stylistic issues like labels on separate lines, but I will mark down for LA R7,5 Put 5 in register 7 Don't tell me what LA does, tell me why you're putting that value in that register. If there is nothing useful to say in the comment, then omit it. ---------------------------------------------------------------------- For IBM-MAIN subscribe / signoff / archive access instructions, send email to [email protected] with the message: INFO IBM-MAIN ---------------------------------------------------------------------- For IBM-MAIN subscribe / signoff / archive access instructions, send email to [email protected] with the message: INFO IBM-MAIN
