Perm url with updates: http://xahlee.org/comp/idiocy_of_comp_lang.html
The Idiocy of Computer Language Docs
Xah Lee, 2011-01-03
Worked with Mathematica for a whole day yesterday, after about 10 years hiatus. Very nice. Mathematica lang and doc, is quite unique. Most other langs drivel with jargons, pettiness, comp-sci pretentiousness, while their content is mathematically garbage. (unixism mumble jumple (perl, unix), or “proper”-engineering OOP fantasy (java), or impractical and ivory-tower adacemician idiocy as in Scheme & Haskell ( currying, tail recursion, closure, call-cc, lisp1 lisp2, and monad monad monad!)) (See: What are OOP's Jargons and Complexities ◇ Language, Purity, Cult, and Deception.)
Mathematica, in its doc, is plain and simple. None of the jargon and pretention shit. Very easy to understand. Yet, some of its function's technical aspects are far more scholarly abstruse than any other lang (dealing with advanced math special functions that typically only a few thousand people in the world understand.).
A Gander into the Idiocies
Here's a gander into the doc drivel in common langs.
In unix man pages, it start with this type of garbage:
SYNOPSIS gzip [ -acdfhlLnNrtvV19 ] [-S suffix] [ name ... ] gunzip [ -acfhlLnNrtvV ] [-S suffix] [ name ... ] zcat [ -fhLV ] [ name ... ] SYNOPSIS zip [-aABcdDeEfFghjklLmoqrRSTuvVwXyz!@$] [--longoption ...] [-b path] [-n suf fixes] [-t date] [-tt date] [zipfile [file ...]] [-xi list]
Here, the mindset of unix idiots, is that somehow this “synopsis” form is technically precise and superior. They are thinking that it captures the full range of syntax in the most concise way. In practice, it's seldomly read. It's actually not accurate as one'd thought; no program can parse it and agree with the actual behavior. It's filled with errors, incomprehensible to human. Worse of all, the semantic of unix software's options are the worst rape to any possible science in computer science. See: The Nature of the Unix Philosophy ◇ Unix Pipe As Functional Language ◇ Unix zip Utility Path Problem.
In Python, you see this kinda garbage:
7.1. The if statement The if statement is used for conditional execution: if_stmt ::= "if" expression ":" suite ( "elif" expression ":" suite )* ["else" ":" suite]
Here, the mindset of the python idiots is similar to the unix tech geekers. They think that using the BNF notation makes their doc more clear and precise. The fact is, there are so many variations of BNF each trying to fix other's problem. BNF is actually not used as a computer language for syntax description. It's mostly used to communicate syntax to humans. Like regex, there are so many incompatible variations. But worse than regex in the sense that there are actually not many implementations of BNF. Real world syntax description languages are usually nothing close to BNF. See: Pattern Matching vs Lexical Grammar Specification.
This incomprehensible BNF notation is the only thing you get if you want to know the basic syntax of “if”, “for”, “while”, “lambda”, or other basic constructs of python.
For much more, see: Python Documentation Problems.
In perl, you see this type of drivel:
A Perl program consists of a sequence of declarations and statements which run from the top to the bottom. Loops, subroutines and other control structures allow you to jump around within the code.
Perl is a free-form language, you can format and indent it however you like. Whitespace mostly serves to separate tokens, unlike languages like Python where it is an important part of the syntax.
Many of Perl's syntactic elements are optional. Rather than requiring you to put parentheses around every function call and declare every variable, you can often leave such explicit elements off and Perl will figure out what you meant. This is known as Do What I Mean, abbreviated DWIM. It allows programmers to be lazy and to code in a style with which they are comfortable.
Perl borrows syntax and concepts from many languages: awk, sed, C, Bourne Shell, Smalltalk, Lisp and even English. Other languages have borrowed syntax from Perl, particularly its regular expression extensions. So if you have programmed in another language you will see familiar pieces in Perl. They often work the same, but see perltrap for information about how they differ.
Notice they introduced you to their lingo “DWIM”. Juvenile humor is a characteristic of perl's docs. It's a whole cult. They have “perl republic”, “state of the onion”, “apocalypse”, “perl monger”, “perl golf”, etc. (See: Larry Wall and Cults.) Another trait is irrelevant rambling. For example, in the above you see: “Perl borrows syntax and concepts from many languages: awk, sed, C, Bourne Shell, Smalltalk, Lisp and even English.”.
For a example of perl doc's maturity and knowledge of math, see: Perl Python Tutorial: Complex Numbers.
However, perl doc overall is more practically usable than Python's.
Here's a example of ivory-tower idiocy, from Haskellers:
Haskell uses a traditional Hindley-Milner polymorphic type system to provide a static type semantics [4, 6], but the type system has been extended with type classes (or just classes) that provide a structured way to introduce overloaded functions.
A class declaration (Section 4.3.1) introduces a new type class and the overloaded operations that must be supported by any type that is an instance of that class. An instance declaration (Section 4.3.2) declares that a type is an instance of a class and includes the definitions of the overloaded operations—called class methods—instantiated on the named type.
For example, suppose we wish to overload the operations (+) and negate on types Int and Float. We introduce a new type class called Num:class Num a where -- simplified class declaration for Num (+) :: a -> a -> a -- (Num is defined in the Prelude) negate :: a -> a
This declaration may be read “a type a is an instance of the class Num if there are class methods (+) and negate, of the given types, defined on it.”
Note the words “Hindley-Milner”, “polymorphic”, “static type semantics”, “overloaded operations”.
The reason they wrote their doc like that is because they are academicians. You might think that their writing is really scholarly, mathematically meaningful, full of rigor, and the daunting appearance must be due to the advanced math ideas by necessity. The irony is that the writing is actually most lousy tech writing. Most of their use of computer science jargons are uncessary to the point of being irrelevant. And, the writing quality is nothing close to the quality of standard math journal's articles.
For some exposition of esoterism, see: World Multiconference on Systemics, Cybernetics and Informatics???.