Python Documentation Author Masturbation

In the Python tutorial “9. Classes” at https://docs.python.org/release/2.3.3/tut/node11.html, it begins thus:

Python's class mechanism adds classes to the language with a minimum of new syntax and semantics. It is a mixture of the class mechanisms found in C++ and Modula-3. As is true for modules, classes in Python do not put an absolute barrier between definition and user, but rather rely on the politeness of the user not to ``break into the definition.'' The most important features of classes are retained with full power, however: the class inheritance mechanism allows multiple base classes, a derived class can override any methods of its base class or classes, a method can call the method of a base class with the same name. Objects can contain an arbitrary amount of private data.

That's classic masturbation.

It continues thus:

In C++ terminology, all class members (including the data members) are public, and all member functions are virtual. There are no special constructors or destructors. As in Modula-3, there are no shorthands for referencing the object's members from its methods: the method function is declared with an explicit first argument representing the object, which is provided implicitly by the call. As in Smalltalk, classes themselves are objects, albeit in the wider sense of the word: in Python, all data types are objects. This provides semantics for importing and renaming. Unlike C++ and Modula-3, built-in types can be used as base classes for extension by the user. Also, like in C++ but unlike in Modula-3, most built-in operators with special syntax (arithmetic operators, subscripting etc.) can be redefined for class instances.

This introduction should be deleted. Nobody gives a shit except a few smug academicians where the author wrote it for pleasing himself. For 99% of readers, it is incomprehensible and irrelevant.

The section immediately follows it: “9.1 A Word About Terminology”, quote:

Lacking universally accepted terminology to talk about classes, I will make occasional use of Smalltalk and C++ terms. (I would use Modula-3 terms, since its object-oriented semantics are closer to those of Python than C++, but I expect that few readers have heard of it.)

is epitome of masturbation. The rest of 9.1 goes:

I also have to warn you that there's a terminological pitfall for object-oriented readers: the word ``object'' in Python does not necessarily mean a class instance. Like C++ and Modula-3, and unlike Smalltalk, not all types in Python are classes: the basic built-in types like integers and lists are not, and even somewhat more exotic types like files aren't. However, all Python types share a little bit of common semantics that is best described by using the word object.

Objects have individuality, and multiple names (in multiple scopes) can be bound to the same object. This is known as aliasing in other languages. This is usually not appreciated on a first glance at Python, and can be safely ignored when dealing with immutable basic types (numbers, strings, tuples). However, aliasing has an (intended!) effect on the semantics of Python code involving mutable objects such as lists, dictionaries, and most types representing entities outside the program (files, windows, etc.). This is usually used to the benefit of the program, since aliases behave like pointers in some respects. For example, passing an object is cheap since only a pointer is passed by the implementation; and if a function modifies an object passed as an argument, the caller will see the change -- this eliminates the need for two different argument passing mechanisms as in Pascal.

The entire 9.1 is not necessary.

Large part of the windy “9.2 Python Scopes and Name Spaces” is again masturbatory.

Most texts in computing are written by authors to defend and showcase their existence against their peers. In a tutorial, nobody cares how the language compared to x y z, or what technicality is it all about, or some humorous snippet of history only funny to the author himself.

Particularly for texts in a tutorial context, you want to write it as simple as possible covering the most useful basic functionality and concepts, and self-contained. Not showcasing your knowledge of history of languages or your linguistic lineage byways.

For example, take this chapter 9 on Objects, it is not difficult to write it without making a show of lingoes. One simply write what is of Python with respect to how it functions, without thinking about relation to xyz languages or in the framework of “computer science” establishment and their ways of thinkings of namespaces and scopes and dynamic and statics and polymorphism … bags of baggage.

Also, in the computing industry, documentations and tutorials often lack examples, especially important in tutorials. Be fewer in words, more in examples. (for example, unix man pages are full of arcane abstract syntactical notations and gut technicalities while most don't contain a single example of usage most users seek.)

This does not mean beginning to write for dummies as the highly successful series of “xyz for Dummies” commercial publications. These sells because the general readers have learned to fear the corpus of textbooks chalking up to jargons and intellectualization on accounts of the author's own esteem and careers at the expense of textbook's educational effectiveness. Dummy books are moronic because they assumed the general readers are morons.

PS Another illustrative case is the official Java Tutorial ( http://java.sun.com/docs/books/tutorial/java/TOC.html last accessed 2012-09-23 ). The Official Java Tutorial is completely asinine. Waxing rocket science with unhelpful and actually misleading drivels throughout, and meanwhile writing as if the readers are 3-year-olds who need instructions step by step repeated multiple times. (e.g. [see Official Java Tutorial on Interface, the Inanity] )

Example of a Tutorial on Objects

In my previous two messages, i've given critique on the inanity that applies to the vast majority of language documentations and tutorials in the industry. I've used the Python tutorial's chapter on class as a example. I've indicated that proper tutorial should be simple, covering just common cases, be self-contained, and be example based; documenting the language's functionality manifest as is. A exemplary case of this style i've indicated is Stephen Wolfram's Mathematica documentation.

Following is excerpt from the a-Python-a-day mailing list. As a example, it shows what i mean by covering the language's functionality as is, sans extraneous lingoe sideshows. If expanded slightly and edited, it can supplant sections 9.0 to 9.4 of the Python tutorial. Languages Tutorials should follow this style.

# in Python, one can define a boxed set
# of data and functions, which are
# traditionally known as "class".

# in the following, we define a set of data
# and functions as a class, and name it xxx

class xxx:
     "a class extempore! (^_^)"
     i=1 # i'm a piece of data
     def okaydokey(self): return "okaydokey"
     def square(self,a): return a*a

# in the following,
# we create a object, of the class xxx.
# aka "instantiate a class".
x = xxx()

# data or functions defined in a class
# are called the class's attributes or
# methods.
# to use them, append a dot and
# their name after the object's name.
print 'value of attribute i is:', x.i
print "3 squared is:", x.square(3)
print "okaydokey called:", x.okaydokey()

# in the definition of function inside a
# class, the first parameter "self" is
# necessary. (you'll know why when you need to)

# the first line in the class definition
# is the class's documentation. It can
# be accessed thru the __doc__
# attribute.
print "xxx's doc string is:", x.__doc__

# one can change data inside the class
x.i = 400

# one can also add new data to the class
x.j=4
print x.j

# or even override a method
x.square = 333
# (the following line will no longer work)
# print "3 squared is:", x.square(3)

# in Python, one must be careful not to
# overwrite data or methods defined in a
# class.

# for a obfuscated treatment with a few
# extra info, see http://python.org/doc/2.3.4/tut/node11.html