Good programming practices (was: Need help in GTK-project)

[Derek Simkowiak <dereks kd-dev com>]

> Why do I need a headerfile for this?  Sorry to ask such stupid
> questions, but this is my first BIG program... at school al always
> learned to program in just one .c file and that was quite stupid I
> think...

	This is actually a big, well-documented topic.  It's called
"modular programming".

	Modular programming is the idea that you split your program into
"modules", where a "module" is a black box of functionality.  This is not
a technical thing, but a matter of policy and programming convention.

	The idea is that if you make a module called, say, "lists" (with
files lists.c and lists.h) which contains an implementation of linked
lists, you could copy those two files into an all-new program and use the
lists over again.

	In C, a module has one .c file and one .h file.  The .h file (the
header) contains the following:

An #ifndef statement like the other person mentioned, so that if someone
else uses a file named "lists.h" it won't conflict with yours.

All of the structs used in your program, with full comments on each of the
struct members.

All of the function declarations with full function descriptions, which
have ALL of the following:

1) Description: Tells what the function does and how it does it.  Should
be one or two paragraphs long.

2) Preconditions: Any conditions which must be true before you can call
this function (i.e., what structs need to exist, what sockets need to be
open, etc.).  Sometimes this is simply "none".

3) Postconditions: Conditions that are made true by your function, for
example "struct foo has member bar set to the current time" or "baz is
freed from memory".  Sometimes this is simply "none".

4) Inputs: Complete descriptions of your function arguments.  
5) Outputs: Complete description of your function's return values,
including error conditions (i.e. "Returns the number of characters in
filename.txt, or <0 if there's an error").  In the future, when you learn
about structured error handling, you'll want to document each of the error
return codes of the function.


Finally, any other #include files needed by your module go in your header 
too.


	The .c file of your module contains only the following:


The line  '#include "module.h"' where "module.h" is the correct name for
your module's header file

All of your function definitions, with comments in the body as needed.


	The idea is that somebody can read your header file (.h) and know
exactly how to use the module, without ever looking at the actual
implementation (.c file).  Also, you should have your .h file completed
and documented before you even create your .c file--that will force you to
have a structured design for your program before you start coding.

	The O'Reilly&Associates book "Practical C Programming" covers this
a bit, and so do most other books on programming design.  See your local
bookstore.

	Note that, despite hundreds of study showing the benefits of
modular programming, people _still_ do not strictly follow the practices
that you'll find mentioned in the books.  They put #include files in their
.c files (so you have to look there to see what other libraries the
module uses) and they don't document the functions, or they'll use
useless descriptions like:

socket_connect()	Connects the socket
[...or...]
reload_file()		Reloads the file


	Once your .h headers are done, write your function *in psuedocode
first*!  Psuedocode is english that looks like C code, i.e.

	for every item in the list
		open a new file in write mode
		write the item to the file
		close the file
		switch to the next item

	set status bar to "All Files Saved"

	This will give you a chance to design the code and algorithms
without worrying about syntax, variable names, etc.  Once you have your
funtions in psuedocode, copy them to a ".c" filename and start
translating.  This stage of software coding goes VERY fast.  By the time
you start coding, your program is basically completed.  And you have the
added bonus of fully commented software, because you just comment out the
psuedocode as you go along:

	/* for every item in the list */
	for (i=0; i < filelist->length ; i++)
[...etc....]


	You may wish to ask some people what coding books they recommend.
I can't think of any off the of my head (and I'm not at home).  But I can
tell you this: I've been through this process many times and, although is
_seems_ like more work, it is actually less work and results in quality
software.

	After you've written some programs, you can learn about revision
control, structured error handling, data hiding (having variables,
structs, and functions in your .c file that are used internally only and
do not exists outside the scope of that single file) and other important
project management and design topics.


--Derek