> 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:[email protected]] On Behalf Of Seymour J Metz Sent: Wednesday, June 16, 2021 1:24 AM To: [email protected] 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 [[email protected]] on behalf of Bob Bridges [[email protected]] Sent: Tuesday, June 15, 2021 6:06 PM To: [email protected] 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, [email protected], cell 336 382-7313 /* While the best judge of Christianity is a Christian, the next best judge would be something more like a Confucian. The worst judge of all is the man now most ready with his judgements: the ill-educated Christian turning gradually into the ill-tempered agnostic, entangled in the end of a feud of which he never understood the beginning, blighted with a sort of hereditary boredom with he knows not what, and already weary of hearing what he has never heard. -from the Introduction to _Everlasting Man_ by G K Chesterton */ ---------------------------------------------------------------------- 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 ---------------------------------------------------------------------- For IBM-MAIN subscribe / signoff / archive access instructions, send email to [email protected] with the message: INFO IBM-MAIN
