[Tutor] code structure terminology and advice

[Alan Gauld]

"Che M" <pine508 at hotmail.com> wrote 

You pretty much answered your own question.

The ultimate answer depends on a few other contextual issues.

> Q1) Generally, what is the best structure for when there are 
> a number of steps/actions that need to be taken?  

A sequence! :-)

> Q2) Is there a term/some jargon in programming that 
> refers to the difference between examples 1-3 below?

Not that I'm aware of.

>  wish to perform four related sequential actions--steps, 
> let's call them--in some part of the program.  

If the entire program consists of those 4 steps (as in a batch 
data processing program, say) then you might structure things 
differently than if the 4 steps are only part of a bigger 
program - one menu option out of several, say.

In the former you would perform the steps in sequence and 
may or may not put them in functions.depending on whether 
they would ever be reused and how long the code was per step.
In most cases the steps are likely to be reusable or of significant 
length so you would put each one in its own function.

> 1. Do the steps all in one function:
> 
> def Function(self):
>   do step1 action
>   do step2 action
>   do step3 action 
>   do step4 action

This would be sensible in the menu selection context.

> 2. Have each step be a function, and have each function 
> call the next function in the chain:

No, this is terrrible from every point of view. It removes any 
opportunity of reuise of individual steps and builds up a deep 
call stack which makes debugging harder and the coupling 
between functions makes maintenance harder (for example 
swapping two steps around in the sequence)

> def StepOne(self):
>    do step1 action
>    StepTwo()

> 3. Make each step a function, but call all of them in order in 
> one master function:
> 
> def MasterFunction(self):
>    self.StepOne()
>    self.StepTwo()

This is just a variation on option 1 and the same applies.

The fourth option you do not consider but which could be the 
best solution for the batch program I discussed is just to perform 
each step from the top klevel of the program, ie no 
enclosing function

StepOne()
StepTwo()
StepThree()
StepFour()


> It seems to me that example 3 is the most sensible.  

In general yes.

> 1 is bad because the steps should be functions, because then they 
> can be easily reused, seen from an IDE explorer, etc. 
> (I guess if they are really minor things it isn't necessary). 

This depends on the size of the steps and the nature of the overall 
programme, but functions would usually be best.

> 2 is terrible 

Yes.

> Maybe there are other and better ways to think about organizing 
> a sequence of steps, and if so I'd love to hear them.  

For longer and more complex processes you could use a table 
or list of functions and step through them in a loop

process = [StepOne, StepTwo,...., stepN]

for step in process:
     step()

Or for dynamically changing sequences you can create or hold 
a sequence list and use that to index a list of steps:

steps = [StepOne, StepTwo,...., stepN]
sequence = [1,2,3,4]

def do Process(sequence)
    for step in sequence:
         steps[step]()

This allows you to selectively peform some of the steps:

sequence = [1,3,4,N]

doProcess(sequence)

Finally for very complex scenarios you might implement a 
state machine where the return value of each step controls 
the next step in the sequence. That can be done by building 
a set of state objects or using a data driven approach with 
a table

You can read about state machines in several places, 
I'd start with Wikipedia.

You might also find that reading about business process execution
languages gives you some ideas about how to structure and 
represent complex processes. BEPL would be a good 
starting point, again try Wikipedia.

HTH,


-- 
Alan Gauld
Author of the Learn to Program web site
http://www.alan-g.me.uk/