Re: how to write a tutorial

From: Xah Lee (xah_at_xahlee.org)
Date: 01/26/05 

Date: 25 Jan 2005 23:12:25 -0800

in my previous two messages, i've criticized the inanity of vast
majority of language documentations and tutorials in the industry. I've
used the Python tutorial's chapter on class as an example. I've
indicated that proper tutorial should be simple, covering just common
cases, be self-contained, and be example based. Documenting or covering
the language's functionalities manifest as it is. An exemplary case of
this style i've indicated is Stephen Wolfram Mathematica documentation.

Following is a tutorial on Python's classes. It is part of a
a-Python-a-day mailing list. As an example, it shows what i mean by
covering the language's functionalities as is, without needing to chalk
up to rocket sciences. If expanded slightly and edited, it can supplant
sections 9.0 to 9.4 of the Python tutorial. Languages Tutorials should
follow this style.

---------------
From: xah@xahlee.org
Subject: [perl-python] 20050124 classes and objects
Date: January 24, 2005 6:44:14 AM PST
To: perl-python@yahoogroups.com

# -*- coding: utf-8 -*-
# Python

# 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 an object, of the class xxx.
# also known as "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

# in Python terminal, type help() then
# topic CLASSES to read about existing
# datatypes as classes, and classes in
# Python

# try to write a class with one data of
# integer and two functions, one
# increases it by 1, one decreases it by
# 1. note: inside a class definition,
# to refer to data inside itself use
# self. e.g. self.i
Xah
  xah@xahlee.org
  http://xahlee.org/PageTwo_dir/more.html

Relevant Pages

  • Re: A Python newbie ask a simple question
    ... the first character in the user supplied response as strings support ... What is the good book to learn Python? ... and having checked out some of the tutorials so you know ... using the Help Index again with "sequence" (since you will probably ...
    (comp.lang.python)
  • language learning vs. process
    ... I'm getting started with python and have almost zero programming experience. ... I'm finding that there are tons of tutorials on the internet -- such as the ... standard tutorial at python.org -- that tell you all about the language. ... I typed "import smtpmail" and it ran -- it ...
    (comp.lang.python)
  • Re: Python docs disappointing - group effort to hire writers?
    ... who is /learning/ the language is, quite frankly, terrifying. ... Currently Python dev seems to be more output than input, ... beautiful tutorials that start at various levels of entry. ... While your student is ...
    (comp.lang.python)
  • Re: how to write a tutorial
    ... majority of language documentations and tutorials in the industry. ... used the Python tutorial's chapter on class as an example. ... this style i've indicated is Stephen Wolfram Mathematica documentation. ...
    (comp.lang.c)
  • Re: New to Python/Programming
    ... programming with a solid foundation of programming principles (OOP, ... I recommend Josh Cogliati's "Non-Programmers Tutorial For Python". ... Work with the online tutorials listed above. ...
    (comp.lang.python)