John Gilmore stated: "Worse, attempts to dispense with such documentation are ill-advised. COBOL is the notorious example of an attempt to make a programming language self-documenting. The attempt failed abjectly, with pernicious side effects because prolixity was misidentified with clarity."
I spent many years writing major applications in COBOL for what is still a major international software vendor. On a rotation, I had to be on call for support for not just the software I worked on, but software written by other groups. It was banking software so a timely fix was critical. Some of the code I had to maintain or provide support for had been written by long-gone programmers.
Unlike John, I feel that COBOL written with the intention of being read is 'self documenting' 98% of the time. Yes, there was that few places where we put some real comments because some calculation or use of subscripts might be vague, but in all practicality, it was 'self documenting'.
I have also seen many 'quick and dirty' programs that were not as self documenting. (They were never intended to be placed into production, but only used by the original programmer, yet somehow were placed into a production status.) BUT(!), even in this case, COBOL was still 'easy to follow' even if not up to the 'self documenting' standard people like John expect.
For many years now, I have coded 98% of code in assembler for vendor system software. For the most part, clear assembler code can easily rise to the level of 'easy to follow', and thus not need a lot of comments. It all depends on using longer variable names and using standard macros to perform some of the seldom used and harder to use instructions. Yet, never have I seen assembler programs that rise to the 'self documenting' level I used to work with when using COBOL.
So, to John, and others, if you really think that COBOL failed in it's intent to be 'self documenting', you have never worked in a shop that lived by the rule 'write clear code because you never know who will have to maintain it at 2am, it might even be you.' It can be done.
As for the current discussion, why would you want to use short versions of macro operands like 'C' for 'Cancel', they have to put a comment in the code that 'this is a Cancel'. That is BS. If using an abbreviation means that you have to add a comment, then don't use (or allow) abbreviations.
Tony Thigpen -----Original Message ----- From: John Gilmore Sent: 07/29/2014 10:57 AM
All of the comments on and objections to the use of CIDTs of keyword-parameter values were interesting, and some of them were drôle. The notion that coding say action=C instead of action=cancel is justified|justifiable if a comment explaining that C really means CANCEL is provided is, I think, self-defeating. If it is required, action=CANCEL should certainly be coded instead. I must again express a very different view. The notion that code should be self-documenting is and always has been chimerical. It should be lucid. Indeed, E. B. White's prescription for good [English-language] prose, that it should exhibit "lucidity, force, and ease", is equally applicable to statements in programming languages. Macro definitions should nevertheless be documented. It is my own practice to include a section called 'coding GUBBINS macro definitions' in a GUBBINS macro definition. This section explains the uses of it [chiefly] keyword parameters, the conventions available for coding them, the kinds of errors, often at boundary values, that can be made in coding them, and (where it is appropriate) a left-recursive BNF definition of the relevant syntax. As this practice suggests, it is my view that non-trivial macros and code in general are not at all self-documenting. Perspicuous names can make them easier to use than they would otherwise be, but clear documentation is always needed. Worse, attempts to dispense with such documentation are ill-advised. COBOL is the notorious example of an attempt to make a programming language self-documentating. The attempt failed abjectly, with pernicious side effects because prolixity was misidentified with clarity. Let me also say something about what Peter Relson calls "explicit abbreviations". I detest them as much as he likes them, and for two reasons. First, they are arbitrary and ad hoc; and ugly ad hoc, special-casing code is required to implement them. Second, they are too often culture-dependent. I can speak and write either British or American English unmixed. Most people cannot and do not need to do so, and they are thus unaware that these two very similar dialects have different abbreviation conventions. Worse, references that are obvious in one language community may be opaque or ambiguous in another. I still recall with pain a long discussion with an English-speaking Italian operator in Milano. The 'z EOD' for 'halt EOD' abbreviation puzzled him. It seemed entirely unmotivated, even though he was aware that 'z' was the last letter of the English (and indeed of the Italian) alphabet. The figurative use of 'z' to mean the end of something other than an alphabet nevertheless eluded him. This puzzled me, and I decided to conduct a small experiment. Knowing that he was a graduate of what Italians call a liceo classico and had thus studied ancient Greek I asked him if replacing 'z' by 'ω', omega, the last letter of the Greek alphabet, would hypothetically be more perspicuous for him; and his immediate answer was yes. He was familiar with the locution "from alpha to omega" as a description of "the complete range", "all possible values", and the like in three languages. It would be easy to multiply examples of this kind, but I have made my point even to those who disagree with it. Arbitrary abbreviations are often tone-deaf to culture and class differences. (Quite stupid upper-class Americans know what a regatta is; brilliant working-class ones usually do not.) Consensus is not likely to emerge from these discussions, but they were not time-wasting. John Gilmore, Ashland, MA 01721 - USA
