[Python-checkins] r46135 - sandbox/trunk/Doc/functional.rst

[andrew.kuchling]

Author: andrew.kuchling
Date: Tue May 23 20:56:47 2006
New Revision: 46135

Modified:
   sandbox/trunk/Doc/functional.rst
Log:
Fill out the introductory section... still pretty rough.
Minor markup fixing.


Modified: sandbox/trunk/Doc/functional.rst
==============================================================================
--- sandbox/trunk/Doc/functional.rst	(original)
+++ sandbox/trunk/Doc/functional.rst	Tue May 23 20:56:47 2006
@@ -50,19 +50,38 @@
 multi-paradigm; you can write programs or libraries that are largely
 procedural, object-oriented, or functional.  In a large program,
 different sections might be written in different styles; the GUI might
-be object-oriented while the processing logic is procedural, for
-example.
+be object-oriented while the processing logic is procedural or
+functional, for example.
 
 In a functional program, input flows through a set of functions. Each
 function operates on its input and produces some output.  Functional
-style discourages the use of data structures that get updated as a
-program runs.  Some languages are very strict about this and even
-discourage the use of assignment statements such as ``a=3`` or ``c = a
-+ b``.
-
-Functional programming may seem like an odd constraint to work under.
-There are theoretical and practical advantages to the functional
-style:
+style avoids making functions have side effects that modify internal
+state or make other changes that aren't visible in the function's
+return value.  Avoiding side effects means not using data structures
+that get updated as a program runs.  Some languages are very strict
+about this and don't even have assignment statements such as ``a=3``
+or ``c = a + b``, but it's difficult to avoid all side effects; some
+Python code, such as a ``print`` statement or a ``time.sleep(1)``,
+returns nothing and is only called for its side effects.  
+
+Python programs written in functional style usually won't go to the
+extreme of avoiding all I/O or all assignments.  The implementation of
+a function will still use assignments to local variables, but won't
+touch any global variables or have other side effects.
+
+Functional programming can be considered the opposite of
+object-oriented programming.  Objects are little capsules containing
+some internal state along with a collection of method calls that let
+you modify this state, and programs consist of making the right set of
+state changes.  Functional programming wants to avoid state changes as
+much as possible and works with data flowing between functions.  In
+Python you might combine the two approaches by writing functions that
+take and return instances representing objects in your application
+(e-mail messages, transactions, etc.).
+
+Functional design may seem like an odd constraint to work under.  Why
+should you avoid objects and side effects?  There are theoretical and
+practical advantages to the functional style:
 
 * Formal provability.
 * Modularity.
@@ -72,13 +91,15 @@
 Formal provability
 ''''''''''''''''''''''
 
-For a long time researchers have been interested in finding 
-ways to mathematically prove programs correct.  This is different
-from testing a program on numerous inputs and concluding that 
-its output is usually correct, or reading a program's source code 
-and concluding that the code looks right; the goal is instead 
-a rigorous proof that a program produces the right result for all
-possible inputs.
+A theoretical benefit is that it's easier to construct a mathematical proof
+that a functional program is correct.
+
+For a long time researchers have been interested in finding ways to
+mathematically prove programs correct.  This is different from testing
+a program on numerous inputs and concluding that its output is usually
+correct, or reading a program's source code and concluding that the
+code looks right; the goal is instead a rigorous proof that a program
+produces the right result for all possible inputs.
 
 The technique used to prove programs correct is to write down 
 **invariants**, properties of the input data and of the program's 
@@ -94,62 +115,68 @@
 assignments can break invariants that were true before the assignment
 without producing any new invariants that can be propagated onward.
 
-Unfortunately, proving programs correct is largely impractical. 
-Even trivial programs require proofs that are several pages long; 
-the proof of correctness for a moderately complicated program 
-would be enormous, and few or none of the programs you use daily
-could be proven correct.  Even if you wrote down or generated a proof,
-there's
-now the question of verifying the proof; maybe you
-only think you've proved that the program correct.
+Unfortunately, proving programs correct is largely impractical and not
+relevant to Python software. Even trivial programs require proofs that
+are several pages long; the proof of correctness for a moderately
+complicated program would be enormous, and few or none of the programs
+you use daily (the Python interpreter, your XML parser, your web
+browser) could be proven correct.  Even if you wrote down or generated
+a proof, there would then be the question of verifying the proof;
+maybe you only ***think*** you've proved that the program correct.
 
 Modularity
 ''''''''''''''''''''''
 
-.. comment
-
-	Small functions that do one thing.
-
-Composability
-''''''''''''''''''''''
+A more practical benefit of functional programming is that it forces
+you to break apart your problem into small pieces.  It's easier to
+specify and write a small function that does one thing than a large
+function that performs a complicated transformation.  Small functions
+are easier to read and to check for errors.  A program that's
+structured into many small pieces is a **modular** program.
+
+
+Ease of debugging and testing 
+''''''''''''''''''''''''''''''''''
+
+It's also easier to test and to debug a functional-style program.
+
+It's easier to debug because functions are generally small and clearly
+specified.  When a program doesn't work, each function is an interface
+point where you can check that the data is correct.  You can look at
+the intermediate inputs and outputs to quickly isolate the function
+that's responsible for a bug.
+
+Testing is easier because each function is a potential subject for a
+unit test.  Functions don't depend on system state that needs to be
+replicated before running a test; instead you only have to synthesize
+the right input and then check that the output matches expectations.
 
-.. comment
 
-	You assemble a toolbox of functions that can be mixed
 
-Ease of debugging
+Composability
 ''''''''''''''''''''''
 
-.. comment
-			Easy to test due to lack of state
-			Easy to verify output from intermediate steps
-
-
+As you work on a functional-style program, you'll write a number of
+functions with varying inputs and outputs.  Some of these functions
+will be unavoidably specialized to a particular application, but
+others will be useful in a wide variety of programs.  For example, a
+function that takes a directory path and returns all the XML files in
+the directory, or a function that takes a filename and returns its
+contents would be useful in many different situations.
+
+Over time you'll form a personal library of utilities.  Often you'll
+assemble new programs by arranging existing functions in a new
+configuration and writing a few functions specialized for the current
+task.
 
 
- 
-		Formal provability
-			Not very relevant to Python
-		Modularity
-			Small functions that do one thing
-		Composability
-			You assemble a toolbox of functions that can be mixed
-		Debuggability:
-			Easy to test due to lack of state
-			Easy to verify output from intermediate steps
-
-Functional programming can be considered the opposite of
-object-oriented programming.  Objects are little capsules containing
-some internal state along with a collection of method calls that let
-you modify this state.
-
 
 
 Iterators
 -----------------------
 
-Iterators are the fundamental Python feature that provides 
-the foundation for writing functional-style programs.
+Iterators are an important foundation for writing functional-style
+programs.
 
 An iterator is an object representing a stream of data that returns
 the data one element at a time.  A Python iterator must support a
@@ -324,7 +351,7 @@
 
 The ``for...in`` clauses contain the sequences to be iterated over.
 The sequences do not have to be the same length, because they are
-iterated over from left to right, **not** in parallel.  For each
+iterated over from left to right, ***not*** in parallel.  For each
 element in ``sequence1``, ``sequence2`` is looped over from the
 beginning.  ``sequence3``  is then looped over for each 
 resulting pair of elements from ``sequence1`` and ``sequence2``.