Re: Elisp programming style

[Eric Schulte <schulte.eric@gmail.com>]

>
> The problem can be described easily: 
>
> problem-specific helper-funcions (some redundancy avoided)
> ,-----------------------------------------------------------
> | (defun main-function (args)                               
> | (let ((var (assoc :key1 args)))  ; extracting var once
> | ...                                                       
> | (helper-function1 ...) ; inside let using var             
> | (helper-function2 ...) ; inside let using var             
> | ))                                                        
> |                                                           
> | (defun helper-function1 ()                                
> | ...                                                       
> | )                                                         
> |                                                           
> | (defun helper-function2 ()                                
> | ...                                                       
> | )                                                         
> `-----------------------------------------------------------
>
> vs
>
> standalone helper-functions (but redundancy)
> ,-------------------------------------------------------------
> | (defun main-function (args)                                 
> | (let ((value (assoc :key1 args))   ; extracting var 1st time
> | ...                                                         
> | )                                                           
> | (helper-function1 ...) ; outside let                        
> | (helper-function2 ...) ; outside let                        
> | )                                                           
> |                                                             
> | (defun helper-function1 (args)                              
> | (let ((var (assoc :key1 args)))  ; extracting var 2nd time  
> | ...                                                         
> | ))                                                          
> |                                                             
> | (defun helper-function2 (args)                              
> | (let ((var (assoc :key1 args)))  ; extracting var 3rd time  
> | ...                                                         
> | ))                                                          
> `-------------------------------------------------------------
>

Hmmm, this looks suspiciously like the case in some Babel functions :)
in which we originally has instances of the first style and then had to
manually transition to the second.  IMO the first is very poor form, the
variables are technically "free variables" when defined in the helper,
and just through undocumented variable capture does the execution work
out correctly, this can lead to unpleasant bugs.

The means the helper may only be used when variables of certain names
are in scope.

If you do want to use a helper which uses variables in scope which
aren't passed as arguments (again just my opinion) you should defined
the helper function using `flet' *inside* of the main function and the
scope of the variables.

>
>
>> In general, if the helper function is only used in a single place and
>> isn't likely to be more generally useful, there might be no reason for
>> it to be a standalone function at all (other than modular programming,
>> which is always a good idea IMO).
>>
>> OTOH, if the helper function _is_ standalone and used in multiple
>> places, then there is no "redundancy", so I'm really not sure what you
>> mean.
>
> Is there a policy? Lets say, an org-library author thinks his helper
> functions will be of no use for nobody else and designs them
> non-standalone. A few years later somebody wants to write a similar
> library and trys to reuse some of the old helper functions, to no avail. 
>
> Would that be considered bad style from the original author, or is that
> up to personal choice and not considered a problem?
>

I don't believe we have an official canon of such rules, but personally
I would consider this to be bad style.  If the helper function is only
used in one main function then it should be defined using flet, if it is
used across multiple functions then the in-scope variables should be
passed as explicit arguments (preferably with names other than those
which it has in scope so you can be sure you are actually using the
arguments).

Finally, I believe the emacs-lisp compiler would complain about such
free variables.

Hope this helps, Best -- Eric

>
> cheers

-- 
Eric Schulte
http://cs.unm.edu/~eschulte/