How to actually write a program?

[Harry George]

"Nick Evans" <nick at huff.org.uk> writes:

> Hello there,
> I have been on and off learning to code (with python being the second
> language I have worked on after a bit of BASIC). What I really want to know
> is, if you are going to actually write a program or a project of some sort,
> how do you actually start.
> 
> Picture this, you know what you want the program to do (its features), you
> have a possably rough idea of how the program will work. You have opened an
> empty text file and saved it as 'mykewlprogram.py' and now your sitting in
> front of an empty text file... Now then.... where do I start.
> 
> Any ideas about this problem :-)
> 
> Ta
> Nick
> 
> 

1. This problem comes up even for experienced programmers.  You may have
done project planning, data models, UML diagrams, GUI story boards,
test suites, etc.  Yet one day you need to mentally shift gears and
actually write code.  A more experienced programmer will have done
some prototyping while working out the requirements and specs, but
even then it is a difficult mental transition.

2. For a total novice, get one of the tutorial books (e.g., "Learning
Python" or "The Quick Python Book") and follow through a few of the
examples.  Don't do all the examples. All you need from this phase is
confidence that you can write working code, and general awareness of
the existence of language features.  ("Yep, I know Python has
exceptions.  Don't know how they work exactly, but I know they are
there.")  You can learn the details when you need them.

Traditionally this exercise is done as a "hello, world" program, with
gradually increasing complexity as you tack on more and more language
features.  It can be the most frustrating program to write in any
language.  The problems are mostly "stupid mistakes" -- that is a
normal part of learning new languages.  [It is also a normal part of
advanced programming, which is why test suites and peer reviews are so
powerful.]

3. Once you can do "hello, world" stuff, then tackle your project.
Assume your first effort will be a bad design, so plan to
"write one to throw away".

Even if the app eventually is a GUI app, start with a batch processing
approach.  Do this by doing a reader/writer process around the data
model.  The "model" (from model-view-controller) is a class with a few
attributes.  The controller is a class that has a sequence of those
class objects, a method to read an input file to load that sequence,
and a method to write the sequence back out.

In fancier settings, there might be persistence via a database or
pickle, or the input and output may be XML or csv.  But for starters,
just use a line-per-record file with ":" field separators.

4. Once the "model-controller" is working, it is time to set up a
proper project.  One approach is my mkpythonproj at:
http://www.seanet.com/~hgg9140/comp/index.html

However you do it, you need a project with documentation, testsuites,
and a setup.py for sdist tarballs.  Put it under config control (e.g.,
cvs or svn).  You may want to factor out the "model" and "controller"
to separate modules.  You are also ready to read good code examples,
so scan "Python Cookbook" and other resources.

Once the project is established, you can begin adding more complexity
to the "model".  More classes, more attributes, more interlationships,
edit routines, etc.  Maybe add more import/export mechanisms (pickle,
csv, XML, etc.).

5. If there is to be a gui ("view"), storyboard (sketch on paper) a
few of the dialogs you will need to drive the "controller" methods.
Assume 1 dialog per model class, plus a tree or list widget
representing the controller's sequence or dictionary of data.

You must decide which toolkit to use.  Tkinter, wxPython, PyQt,
PyGTK are the main contenders.  Now, set aside all the work you've
done so far and concentrate on learning the GUI toolkit.  Get a main
window working, with menus, file open/close, exit.  The file
open/close of course call the file reader/writer you already have
working.  

Next build a dialog to edit one of the classes, using the same edit
routines you have already developed.  Hook the dialog to the "edit"
submenu.

Tag the release in your config control system, and make a tarball
(version 0.1).

6. By now you have a much better grasp of the project, the language
and the available libraries.  It is time to rethink the project.

Print out the code ("enscript --line-numbers --landscape" is a good
choice).  Read it.

Do this mental exercise: You have an opportunity to work on a
wonderful new project, if only you can train a replacement for
maintaining the current project.  If you fail to train the
replacement, of if they leave in disgust, you are doomed to maintain
your own code forever.  What can be done to make the handoff painless?
Refactor?  More systematic approach to method naming?  Better
"developer's guide" documentation?  Move hard-coded values to tables,
config files, dictionary lookups?

I find that on some projects, I can fix the code in situ.  Most times,
I just make a whole new project and start fresh.  Either way, the
target is code clean enough to be a pleasure to read and maintain.




-- 
harry.g.george at boeing.com
6-6M21 BCA CompArch Design Engineering
Phone: (425) 342-0007