Total newbie question: Best practice

[Dave Angel]

On 11/29/2011 03:06 PM, Colin Higwell wrote:
> Hi,
>
> I am just starting to learn Python (I have been at it only a few hours),
> so please bear with me. I have a few very small scripts (do you call them
> scripts or programs?) which work properly, and produce the results
> intended.
>
> However, they are monolithic in nature; i.e. they begin at the beginning
> and finish at the end. Having done a little reading, I note that it seems
> to be quite common to have a function main() at the start (which in turn
> calls other functions as appropriate), and then to call main() to do the
> work.
>
> Is that standard best practice?
>
> Thanks
>
Welcome to Python, and to the comp.lang.python list. Is this your first 
experience programming?

Yes, factoring your code from "monolithic" to "modular' (several 
functions, or even functions and classes), is good practice.

That's not to say that some problems don't deserve a monolithic answer, 
but if you're a beginner, i'd like to see you get into a modular habit.

You can use the words script and program pretty much interchangeably.  
in some contexts, each has additional connotations.  For example, 
somebody used to a compiled language may refer to a python source file 
as a script, implying it's not as sophisticated as his own product.  
But, closer to home, we usually refer to the file you directly pass to 
the interpreter as a script, and any added files that get imported, as 
modules, or libraries.

Other times, people will refer to a simple program as a script, implying 
that all it does is invoke some standard library functions, or even run 
some external programs.  But when it gets more complex, it gradually 
turns into a  "real program."


Why break up a monolith?

Several reasons.  If you factor the code into independent functions, and 
give them good names, then each piece of the program is easier to 
understand.  You will especially appreciate that if you come back to the 
code after doing something else for two weeks.  Similarly if somebody 
else has to take over your code, or maybe adapt it to a slightly 
different purpose.

Next, if it doesn't quite work, you can exercise the individual pieces 
independently, and narrow down the problem more quickly.

Next, if the progfram is slow, usually you can narrow it down to a few 
key functions that take most of the time.  You can write two versions of 
the same function, and do some careful timings to decide which one to use.

Next, some of those functions may be useful in the next program you 
write.  If you "reuse" the code by copy & paste, and find a problem in 
the new one, it's quite possible that the same problem may exist in your 
first program.  it's easier to bring those changes back if they're in a 
function than if they're in lines 14 through 71.

Finally, some of that reusable code may be worth moving to an external 
file, called a module.  Then the same copy can be literally shared 
between multiple projects.  This is how libraries were born, and you can 
write your own, eventually.

there are many other reasons, but some of them might not make sense to 
you yet.


How do you break it up?

First, separate the classic parts that most scripts will have.  Put the 
imports at the top, along with a comment describing the whole progfram's 
purpose.  Next put the global variables, which should be few.  If there 
are any constants, use all UPPERCASE for their names.

Next, put the function and class definitions.  Notice that none of them 
will be called yet, so the order of execution isn't important to the 
compiler.  Each function needs a name, and you should use a name that 
makes sense to you.  Try to write functions that work at a single level 
of complexity, and do one complete operation.  Try not to do 
input/output in the same functions that do the computation.

And finally, put the actual mainline.  It could be as simple as a call 
to main(), but it may make more sense to you to put the calls to 
argument processing here, rather than in a main function.  By arguments 
here, i'm referring to the stuff you typed on the command line when youi 
invoked the script.  This part of the code is where you do the magic 
incantation:

if __name__ == "__main__":
     main()



When the number of functions gets unwieldy, it's time to move some of 
them to a new file.  They should be related, and should work at the same 
level of complexity.  And the file name should remind you of their 
purpose.  At that point, you add an import of that file to your main 
source script.  Congratulations, you've created a module.

One catch with writing a lengthy reply is that others have already given 
you good feedback.  Hopefully, mine will complement theirs.

-- 

DaveA