On Jan 4, 12:24 pm, Xah Lee <xah...@gmail.com> wrote: > a opinion piece. > > 〈The Idiocy of Computer Language > Docs〉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. > > ------------------------------ > unix > > In unix man pages, it starts with this type of garbage: > > SYNOPSIS > gzip [ -acdfhlLnNrtvV19 ] [-S suffix] [ name ... ] > gunzip [ -acfhlLnNrtvV ] [-S suffix] [ name ... ] > zcat [ -fhLV ] [ name ... ] > > SYNOPSIS > zip [-aabcddeeffghjkllmoqrrstuvvwx...@$] [-- > 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. > > ------------------------------ > Python > > 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] > > (Source docs.python.org) > > 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 > variations. But worse than regex in the sense that there are actually > not many actual implementations of BNF. Real word syntax description > language 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. > > ------------------------------ > Perl > > 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. > > (Source perldoc.perl.org) > > Notice they introduced you to their lingo “DWIM”. Juvenile humor is a > characteristics 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.”. > > However, perl doc overall is more practically usable than Python's. > > ------------------------------ > Haskell > > 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.” > > (Sourcewww.haskell.org) > > 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, almost provably correct, full of dense > mathematical rigor, and necessarily hard to understand because of the > advanced math ideas. By the look of it it is really daunting. The > irony is that the writing is often imprecise, most use of tech jargons > and terms are absolutely uncessarily to the point of being irrelevant. > And, the writing quality is pretty bad, far below the quality of > standard math journal's articles. > > -------------------------------------------------- > > uhmm, happy 2011. > > Xah ∑http://xahlee.org/☄
Fell free to rewrite the docs of those programming languages in iambic pentameter, adding harp octaves in the background. -Ramon -- http://mail.python.org/mailman/listinfo/python-list
