opinion: comp lang docs style

[Terry Reedy]

On 1/4/2011 1:24 PM, an Arrogant Ignoramus wrote:

what he called
> a opinion piece.

I normally do not respond to trolls, but while expressing his opinions, 
AI made statements that are factually wrong at least as regards Python 
and its practitioners.


1. He correctly notes that the Python Language Reference includes 
snippets of BNF grammar with the intention of making the doc clear and 
precise.

>      The if statement is used for conditional execution:

>      if_stmt ::=  "if" expression ":" suite
>                   ( "elif" expression ":" suite )*
>                   ["else" ":" suite]

He incorrectly claims that the inclusion fails in its purpose. This is 
based on the irrelevant fact that 'BNF' has many versions (Python only 
uses one, explained in 1.2. Notation) and the false claim that "BNF is 
actually not used as a computer language for syntax description.".

Actually, the above snippet is a quotation (with initial ':' expanded to 
'::=' and newlines added) from the file Grammar/Grammar:
"if_stmt: 'if' test ':' suite ('elif' test ':' suite)* ['else' ':' suite]"

The CPython program Parser/pgen takes Grammar/Grammar as input and 
produces the parser tables that CPython uses to parse Python code. In 
other words, CPython uses its well-defined version of extended BNF as a 
'computer language for syntax description', contrary to AI's claim. I 
presume other implementations make either human or machine use of the 
same file.

2. AI also claims that this notation is 'incomprehensible'.
Perhaps to him, but not to me or most the the subset of users who care 
about it. One way to expand the BNF into English is as follows:

An if-statement starts with an if-clause consisting of the word 'if', an 
expression, a colon, and a suite. 'expression' and a 'suite' have 
already been defined elsewhere. The if clause can optionally be followed 
any count (including 0) of elif-clauses which are the same as if-clauses 
but with 'elif' substituted for 'if'. An if-statement can optionally be 
terminated with an else-clause consisting of 'else' and a suite.

Even if such long-winded paraphrases were added to the doc (and I do not 
think they should be), in addition to the explanations currently given, 
the grammar snippet would still be needed to show the exact technical 
definition that CPython actually uses, for those who wan precisely that. 
(The people who care include those who want to change the grammar or 
those who think the behavior might might match the grammar.)


3. AI's complaint is deceptive and deficient in omitting any mention the 
part of the docs *intended* to teach beginners: the Tutorial. The main 
doc pages list the Tutorial first, as what one should start with. That 
is where I started and I cannot remember if I have ever read the formal 
if-statement grammar before, as I knew how to write such before I ever 
looked at the Language Reference. Guido and other developers do not and 
never have expected people to learn about if-statements from the 
grammar. The tutorial says:
"
4.1. if Statements
Perhaps the most well-known statement type is the if statement. For example:

 >>> x = int(input("Please enter an integer: "))
Please enter an integer: 42
 >>> if x < 0:
...      x = 0
...      print('Negative changed to zero')
... elif x == 0:
...      print('Zero')
... elif x == 1:
...      print('Single')
... else:
...      print('More')

There can be zero or more elif parts, and the else part is optional. The 
keyword ‘elif‘ is short for ‘else if’, and is useful to avoid excessive 
indentation. An if ... elif ... elif ... sequence is a substitute for 
the switch or case statements found in other languages.
"

I think this says by example and plain English just what a Python 
programmer needs to know. It is, of course, followed by many other 
examples in the remainder of the tutorial.

If one wants to critique the 'Python Docs', especially as regards to 
usefulness to beginners, one must start with the Tutorial; and if one 
wants to use if statements as an example, one must start with the above.

-- 
Terry Jan Reedy