I was on one project that did that, with XEDIT macros to make it easier to adhere to our standards. For the initial design review a module was boilerplate plus comments. When there was a design change then the the existing code was left alone and the design comments were update prior to the design review. The biggest hassle was getting people to read everything before the reviews. I never understood why code and design reviews weren't universal.
-- Shmuel (Seymour J.) Metz http://mason.gmu.edu/~smetz3 ________________________________________ From: IBM Mainframe Discussion List [IBM-MAIN@LISTSERV.UA.EDU] on behalf of Jesse 1 Robinson [jesse1.robin...@sce.com] Sent: Wednesday, June 16, 2021 1:44 PM To: IBM-MAIN@LISTSERV.UA.EDU Subject: Re: Coding for the future Can't say I ever participated, but I've heard the strategy of writing only comments, then gathering a group of folks in a room to review the 'code'. Participants don't need to know the underlying language, or any language for that matter. It sounds exciting. . . J.O.Skip Robinson Southern California Edison Company SHARE MVS Program Co-Manager 323-715-0595 Mobile -----Original Message----- From: IBM Mainframe Discussion List <IBM-MAIN@LISTSERV.UA.EDU> On Behalf Of Charles Mills Sent: Wednesday, June 16, 2021 9:29 AM To: IBM-MAIN@LISTSERV.UA.EDU Subject: (External):Re: Coding for the future *** EXTERNAL EMAIL - Use caution when opening links or attachments *** > I developed the habit of writing documentation first A thousand and one +1's!!! I can't say that I always do it, but I can say that I am always happier with the result when I do. It is usually easier to write code that implements some easy-to-explain function than to write documentation that explains code that was simple to write at the time. Does that sentence make sense? In other words, write documentation that clearly explains what will be accomplished by the function. You are probably talented enough to write code that implements it. OTOH if you write the code first you may write code that makes sense when you write it, but that ends up being very hard to explain. Charles -----Original Message----- From: IBM Mainframe Discussion List [mailto:IBM-MAIN@LISTSERV.UA.EDU] On Behalf Of Seymour J Metz Sent: Wednesday, June 16, 2021 1:24 AM To: IBM-MAIN@LISTSERV.UA.EDU Subject: Re: Coding for the future Well, I was 16 when I started, so bad habits were predictable. The worst was using arbitrary labels because I could. I never hated long variable names. However, I do use single letter names for control variables in extremely short loops. I don't use long names as an excuse for pretending that code can be self documenting - I still write comments. I didn't comment adequately in my early years. Within a few year I routinely had comments up front describing, e.g., the meaning of each parameter. On the flip side, I got into the habit of using symbolic register names so that registers would show up in the XREF listing, but that's no longer necessary. > 4) This isn't exactly a bad-coding issue, but as much as possible I > want the > input arguments on a command to come in any order I happen to think of them > at the time. That's one of the few weaknesses of REXX compared to CLIST; no keyword parameters. It's actually easier to parse TSO command operands in assembler than in REXX. I wish that REXX included XPARSE, or an equivalent to the Perl Getopt::Long package. Even the PROC statement of CLIST would be an improvement. > i'm just curious about other issues that y'all are careful about that maybe > you weren't when we were young and foolish. It's been decades since I wrote any MVS code that wan't reentrant and refreshable. I try to avoid monolithic code blocks and relegate major sections to subroutines even if I only use them once. Tricky code requires good comments. The cleverest code is when the reader asks "Why didn't I think of that?". Obscure code contests are for recreation, not for code that has to work correctly and be maintained. I used to write throw-away tools in the sure and certain knowledge that I would only use them once. These days I am a lot less confident about predicting that I'll never have to update them. I developed the habit of writing documentation first, and changing the documentation before changing the code. It has served me well. I've found that seeking a fresh pair of eyes to spot a bug can overcome a mental blind spot; in the process of explaining how the code is supposed to work, I sometimes have an "Oh! Never mind." moment. Code reviews and design reviews are not fads. If I have to patch, I use a zap-maker. -- Shmuel (Seymour J.) Metz http://mason.gmu.edu/~smetz3 ________________________________________ From: IBM Mainframe Discussion List [IBM-MAIN@LISTSERV.UA.EDU] on behalf of Bob Bridges [robhbrid...@gmail.com] Sent: Tuesday, June 15, 2021 6:06 PM To: IBM-MAIN@LISTSERV.UA.EDU Subject: Coding for the future In a recent email one of our number, whose name I won't mention except to say that his initials are Jeremy Nicoll, made a comment that got me thinking about ~my~ past and present coding habits. Like most programmers (maybe), I had some habits that I no longer tolerate. For example: 1) I used to hate long-winded variable names. Ok, that's a bad example to start with, because I still do. But I no longer use one-character variable names, ever; I use two- to four-character names if they're to be used only in one brief section, but if they're supposed to last longer I make them more descriptive; and even the shorter ones follow a naming standard that I'm familiar with. It wouldn't be any help to someone else who had to modify my code, though. 2) I know everyone says to comment your work, but I never used to. "I'm the only one who'll use this code", I thought, "and I know what I did". Oh, fool! I can forget what I was doing a mere two months later, much less two years or two decades. So now I'm more likely to use one-line comments on every other line and a paragraph at the head of each section. Well, perhaps I exaggerate, but not much. 3) Not for me, any longer, to assume that my TSO commands will work correctly. For pretty much every interaction with the outside world I include checks for file-not-found, empty datasets, missing non-optional arguments, anything I can think of. I want my programs to go on working long after I've forgotten how to invoke them properly. 4) This isn't exactly a bad-coding issue, but as much as possible I want the input arguments on a command to come in any order I happen to think of them at the time. My routine to search through a concatenation of PDSs for a particular module has to receive the DD and module name in a particular order, but mostly it's possible to say "tso command arg1 arg2 arg3" or "tso command arg2 arg1 arg3" without any confusion. 5) One thing hasn't changed: Like most of us here, I was ~always~ rabid about proper indentation. (Where by "proper" I mean "consistent"; I know styles can vary, but as long as there's no variation...) I'm just curious about other issues that y'all are careful about that maybe you weren't when we were young and foolish. --- Bob Bridges, robhbrid...@gmail.com, cell 336 382-7313 ---------------------------------------------------------------------- For IBM-MAIN subscribe / signoff / archive access instructions, send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN ---------------------------------------------------------------------- For IBM-MAIN subscribe / signoff / archive access instructions, send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN
