========================================================================
Contributing guidelines for the Palm OS Emulator
Copyright (c) 1999-2001 Palm, Inc. or its subsidiaries.
All rights reserved.

Please send bug reports, comments, suggestions, etc. to
<mailto:bug.reports@corp.palm.com>
========================================================================

The Palm OS Emulator is distributed under and protected by the GNU
GENERAL PUBLIC LICENSE (the full copy of which is found in _GPL.txt).
We make the source code available so that others can alter it for their
own needs.  We do request you submit your changes back to us so that we
can merge them into the main version of the product, but there is no
requirement that you do so.  Changes can be submitted to the current
maintainer (<mailto:keith.rollin@corp.palm.com>) or Palm Developer
Support (<mailto:bug.reports@corp.palm.com>).

If you make changes and submit them back to us, all I ask is that you
follow a few guidelines.  The general theme of these guidelines is to
follow the programming conventions you already find in the source code.
I don't want this thing to look like a patchwork quilt; it should look
like it was written by just one person.

*	Naming conventions: I use MacApp's naming conventions:

	Function names begin with upper case letters (e.g., SomeFunction).
	Local variable begin with lower case letters (e.g., myVariable).
	Global variables begin with a "g" (e.g., gCachedData).
	Data members begin with an "f" (e.g., fFieldOfDreams).  However,
		I'm flexible on this one.  I think the UNIX guys are using
		"_" for the UNIX-specific portions, and there are probably
		still some Mac sections that use "m".
	Static data members begin with "fg" (e.g., fgDebuggerData).
	Constants start with a "k" (e.g., kTicksPerSecond).

	To help clean up the namespace a little bit, data types (classes,
	structs, typedefs, etc.) and file names start with the "Em"
	prefix.  You may see a mix of this now in the sources, because
	I'm slowly moving over to that convention.  Using the "Em"
	prefix for types is more "primitive" that using actual namespaces,
	but it's simpler (easier to type).

*	Use classes and objects only where it makes sense.  There's no need
	to go overboard.

*	You'll see some places where I use classes with all-static members
	to emulate namespaces.  This approach was used before CodeWarrior
	supported namespaces.  Now that it does, I've started using
	namespaces.  However, neither CodeWarrior Pro 5 nor VC++ 6.0
	support namespaces in their browsers, so choose which method you
	like if you introduce a new namespace.

*	By convention, I use pointer types (e.g., "void*") for referencing
	data in the host computer's space, and the UAE type "emuptr" to
	reference data residing in the emulated Palm OS space.  (This
	comment may not make much sense now, but come back to it later
	once you've looked over the sources and learned how Palm OS
	memory is emulated.)

*	Braces go like this:

		if (...)
		{
			...
		}

	And the contents always move to the right.  None of this in-and-out,
	back-and-forth GNU stuff.

	I generally like to use braces even if there is only one line
	in between them, but I'm not adamant about that.

*	One statement per line.  None of this stuff:

		if (...) DoSomething();

*	Comment all functions using the following template:

		/***********************************************************************
		 *
		 * FUNCTION:	
		 *
		 * DESCRIPTION:	
		 *
		 * PARAMETERS:	none
		 *
		 * RETURNED:	nothing
		 *
		 ***********************************************************************/

	Not all functions are currently like this, but I'm working on that.

*	Call global functions using "::". E.g.:

		::SomeGlobalFunction ();

	Again, not all of Poser sources follow this convention, but I'd
	like to stick to it.

*	No platform-specific calls in the cross-platform files.  If you find any
	counter-examples to this rule, it's a bug.

*	Let's not go overboard with STL.  Yes, I know you can write a MasterMind
	program in one line with it (true!), but let's keen this sane.


Anyway, I'm flexible on most of this stuff.  These are merely guidelines.  I'm
just asking that you keep them in mind if possible.

Thanks,

-- Keith Rollin
-- Palm OS Emulator engineer
