

\documentstyle{article}

\setlength{\oddsidemargin}{0in}
\setlength{\evensidemargin}{0in}
\setlength{\topmargin}{0.0in}
\setlength{\headheight}{0in}
\setlength{\headsep}{0in}
\setlength{\textwidth}{6.5in}
\setlength{\textheight}{9.4in}
\setlength{\parindent}{0in}
\setlength{\parskip}{0.12in}

\begin{document}

\newcommand{\bfs}[1]{{\bf #1}}
\newcommand{\lnum}[1]{{\medskip \bf Line #1:}}
\newcommand{\lnums}[2]{{\medskip \bf Lines #1-#2:}}

\begin{center}
{\LARGE\bf Programming Style and Practice

\end{center}

\bigskip

\section{Use Top-Down Design!}

\begin{itemize}
\item [(a)]
Keep all functions very short, say at most a 25-line screenfull.  

\item [(b)]
Most functions, including main(), should contain a number of calls to 
further functions.

\item [(c)]
Variables and functions should have meaningful names.  This way one can 
glance through a program and get a quick overview of what actions are 
done.

\item [(d)]
Make sure that each function does what the name you've given it
implies---no more and no less.  If you have a function named
ClearScreen(), for example, make sure that (i) it \underline{does}
clear the screen, and (ii) it does \underline{not} do some
unrelated task, such as reading in the name of an input file.
\end{itemize}

\section{Use Meaningful Indenting!}

The following is C convention.  Use it!

Every compound statement, i.e. a set of statements enclosed by \{ and \}
(analogous to begin/end in Pascal) should be indented further to the
right than its ``parent'' statement (the latter being one of \bfs{if}, 
\bfs{else}, \bfs{for} or \bfs{while}).  The \{ and \} are arranged in
a ``triangular'' form.  E.g. for a \bfs{while} loop:

\begin{verbatim}
while (...) {
   statement
   statement
   statement
   ...
}
\end{verbatim}  

This is used in the same way for \bfs{for} loops and if-then-else:

\begin{verbatim}
for (...; ...; ...) {
   statement
   statement
   statement
   ...
}  
\end{verbatim}

\begin{verbatim}
if (...) {
   statement
   statement
   statement
   ...
}
else {
   statement
   statement
   statement
   ...
}
\end{verbatim}

For example, if I have a rather long \bfs{while} loop, someone who
reads my program should be able to easily find the end of the loop,
simply by going straight down from the `w' in `while'.

\section{Include Lots of Comments!}

Every major variable declaration should have a comment explaining what
that variable does.  Most functions should have comments at the
beginning, explaining what the functions do.

\section{Do These Things from the Beginning---Not Just When You Submit
the Program for Grading!}

Employ these devices---top-down style, indenting and comments---in
all your programs, {\bf from the moment you start writing them,
not just when you are done writing!}  You will save yourself a lot of
time, both in writing and in debugging.  Use of top-down style is especially
important.  It will help your thinking process tremendously during the time
you are writing the program.  You may have been told in the past that this
is to help {\it other} people, i.e. to help other people read your program;
that is true, but it is also to help \underline{yourself}!  It \underline{will}
save you time!

\section{Use Windows!}

Make \underline{full} use of X11 windows if you at a workstation console;
otherwise use the `screen' program to get windows.  And in either case,
use emacs, with its nice windowing features; e.g. when editing a program
file and adding a call to a given function, you can have one window at
the call and another window at the function, so that you can check that
the parameters match up correctly.

\section{There Is No Need to Use Any Paper!}

If you are using top-down design, comments and windowing properly, you 
should \underline{not} need to use any paper:

\begin{itemize}
\item [(i)]
During the time you are doing your initial writing of the program, you
should \underline{not} write your program on paper.  You can compose
your program right there at the terminal, using the editor, not paper.
First, enter the declarations of your major global variables, with
comments for each one, explaining what the variables are for.  Then
write your function main(); most of it should consist of calls to
other functions.

\item [(ii)]
During the time you are debugging your program, do \underline{not}
make a printed copy of your program.  With good top-down design,
you should not need a hard copy to find where in the program you 
perform a given task.  With the use of windows, you should not need
a hard copy so that you can look at two different parts of the 
program at the same time.
\end{itemize}

\end{document}



