[GeneralDiscussion] clarifying state dependencies

A couple of days away from keyboard are good for thinking. After  
another productive chat with betabug this morning, I have added some  
new guidelines to the developer style guide, which I include here for  
your interest and critique.


Function/method contracts
-------------------------
We are considering ways to document function and method "contracts".
`Here's <http://www.htdp.org/2003-09-26/Book/curriculum-Z-H-5.html#node_sec_2.5 
 >`_
an example. We are most interested in

- their input (argument) and output (return value) types

- their degree of statefulness/statelessness. Are they

   - pure functions depending only on the arguments ?
   - well-behaved methods which depend on/modify only self ?
   - or do they depend on/modify other pages, the wiki folder, other  
things ?

Understanding statefulness in particular should help us to identify and
gather together the most stateful code, reduce state dependencies, and
increase the proportion of pure and semi-pure functional code, which
will greatly aid testing, debugging and reliability.

Here is a possible convention for now: when you touch code, review the
docstring and try to add a comment to the function definition
describing (a) the return type(s), (b) state that it depends on other
than the arguments, if any, and (c) state that it modifies other than
the return value, if any.  Even a rough guess at the state
dependencies could be helpful. Here are some examples. The dependency
on self for permission checking is omitted.::

   def method(args) # -> return value type(s) [; depends on: ...] [;  
modifies: ...]

   def htmlquote(self, text): # -> string

   def asAgeString(self,time): # -> string | empty string ; depends  
on: self (for current time)

   def excerptAt(self, expr, size=100, highlight=1, text=None):  # ->  
html string | empty string ; depends on: self (if no text provided)

   def revisionNumberBefore(self, username): # -> revision number |  
none ; depends on: self, revisions

   def handleSubtopicsProperty(self,subtopics,REQUEST=None): # ->  
none ; modifies: self

   def expungeEditsEverywhereBy(self, username, REQUEST=None,  
batch=0): # -> none ; depends on: all pages, revisions ; modifies: all  
pages, revisions

   def upgradeAll(self,render=1,batch=0,REQUEST=None): # -> none;  
depends on: wiki; modifies: wiki (folder, pages, dtml methods,  
catalog, outline, revisions..)


--
forwarded from http://zwiki.org/GeneralDiscussion#[email protected]