Code should ideally be self-commenting as otherwise the comments get stale. So adding one saying "C here really means CANCEL" might be a benign version of that but it's still subject to becoming wrong.
Cheers, Martin Martin Packer, zChampion, Principal Systems Investigator, Worldwide Banking Center of Excellence, IBM +44-7802-245-584 email: martin_pac...@uk.ibm.com Twitter / Facebook IDs: MartinPacker Blog: https://www.ibm.com/developerworks/mydeveloperworks/blogs/MartinPacker From: Peter Relson <rel...@us.ibm.com> To: ASSEMBLER-LIST@listserv.uga.edu Date: 29/07/2014 13:19 Subject: Re: The rationale for using macros i Sent by: IBM Mainframe Assembler List <ASSEMBLER-LIST@listserv.uga.edu> I am envious of John Gilmore. He must have a far better memory than do I. To me, this comes down to readability, as that, in my opinion,is the most important legacy that a coder can leave for those who follow him/her in trying to deal with a module. Consider an example where my macro accepts REQUEST=C as a shorthand for REQUEST=CANCEL. When John reads module source with an invocation of my macro with ...REQUEST=C he must remember that C stands for CANCEL and not something else; I often do not. Thus I agree completely with EJ. You are not overly concerned about someone reading what command you entered (as they would likely be doing so only if analyzing a dump or trying to figure out what command was actually entered that did something you did not appreciate). But you should be extremely concerned about subsequent readers of your code. And why make those readers struggle over what REQUEST=C means? In good conscience if I were to use REQUEST=C I would accompany that with a comment that I was doing a CANCEL. But I prefer not to make my code need such pedestrian comments since simply coding REQUEST=CANCEL makes it fully clear without the additional commentary. And of course coding both REQUEST=C and having a comment that says CANCEL is even more keystrokes than just coding REQUEST=CANCEL. I also disagree with the thought that implicit abbreviations (such as the shortest, unique string) are a good thing. Very little annoys me more than something that I've gotten very used to (and that really is an interface) such as "you can enter C for CANCEL" no longer works because some other option has made "C" no longer uniquely representative of CANCEL. It is often unreasonable for the new option to avoid such a collision by requiring a different structure or a different name. Explicit abbreviations, on the other hand, for commands are very nice. Because then you know that what your fingers have learned to type is likely to remain valid. If C were an explicitly documented shorthand for CANCEL, then even if CONTINUE were made a choice, C would still be shorthand for CANCEL. Peter Relson z/OS Core Technology Design Unless stated otherwise above: IBM United Kingdom Limited - Registered in England and Wales with number 741598. Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU
