===========================
Syntax Organization Outline
===========================

By Nate Miller -- 4/14/99

===============================================================================
Introduction
===============================================================================
	As I have become a proficient programmer in the C language I have focused
more and more on what my code looks like and the way it is structured.  Part of
becoming a programming in my mind is looking at the source code of others to 
pick up new techniques and new ways to attack problems.  The readability of a persons
source code greatly effects the amount of information that an individual can obtain
from it.  In my personal experiences source code that has been well formatted and
well commented has been the easiest to learn from while source with odd methods 
and structures proved less useful in my quest for knowledge.  Also when I format
my source code well and document my work I have found that at a later date I was
able to return to the older source to plant the seeds for new ideas.  The point 
of this document is to clarify my thinking on how I structure my code.  I will
outline the way in which I structure my programs in the hope that I will stick to 
one method rather than jumping from one to another.  

===============================================================================
Variable Naming
===============================================================================
	First word all lower case.  All following words start with a capital letter.  
	
Examples:
	int playerPos;
	int winW;
	int winH;
	int time;
	char *player
	int nodesInTree;

===============================================================================
Function Naming
===============================================================================
	Same naming convention as Variables.  First word all lower case.  All 
following words start with a capital letter.  
	
Examples:
	int getWindowPos (...);
	bspTree_t loadBSPTree (...);
	char *loadTarga (...);
	void initGL (...);

===============================================================================
Syntax Spacing
===============================================================================
	Since I can't explain this I will just write up a simple example of how
I space my syntax in a sample function.  Note: this is code is just made up and
serves really no purpose.    

void dispString (char *string)
{
	int len = 0;

	while (*string)
	{
		printf ("%c", *string ++);
		len ++;
	}
	printf ("\n");
	printf ("Displayed a string of %d chars\n", len);
}

===============================================================================
Commenting
===============================================================================
	Again this is difficult to explain so I will post a simple example.  My
commenting system is pretty simple.  Include a description of the function if needed
and any additional comments that fit on a single lines use // above the line.  A 
multiple line comment needs the use of /* */.  

/*
	convertImage -- Converts a RGB image to a RGBA image.  
	returns 1 on success and 0 on failure
*/
int convertImage (int w, int h, char *s, char *d)
{
	char *rgb;
	char *rgba;
	int size = w * h;

	printf ("Attempting to convert %s (%d X %d) to RGBA...\n", s, w, h);

	// load the rgb data from a file
	rgb = loadRGB (size, s);
	
	if (!rgb)
		return 0;

	// convert the rgb to rgba
	rgba = toRGBA (size, rgb);
	
	if (!rgba)
		return 0;

	// write the rgba to the destination file
	writeRGBA (size, d, rgba);

	/*	
		Make sure that we free the memory,
		leaks are bad! 
	*/	
	free (rgb);
	free (rgba);

	printf ("Done!\n");

	return 1;
}	

===============================================================================
Conclusion
===============================================================================
	In conclusion I hope that I follow the method which I have outlined here.  
I feel that the description of a function would be used the most in larger projects
where there will be a large mass of code.  In smaller sample applications the 
description is not really needed.  I really hope that writing out the method I will 
use for structuring my programs will help me become a better programmer and allow
me to write source code that can be used by many others rather than just by me.