======================================================================== 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 ======================================================================== 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 () or Palm Developer Support (). 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). Private function names begin with "Prv" (e.g. PrvHelperFunction). This includes static functions (local to a single file) and private member functions. Local variables 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). File guards are based on the name of the file, with the '.' replaced with an underscore. Thus, the fileguard for EmWhizzyHeader.h is EmWhizzyHeader_h. File guards are placed only in the header; they are not used to control the inclusion of the header from another file. * 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 (...) { ... } I use this approach because it is consistant with the bracing rules for function bodies, it's easy to match up the begin and end of a block, and because it's easy to comment out the "if" statement in order to make the block unconditional. People trying to comment out the "if" statement when it also includes the left brace at the end have to deal with finding and commenting out the right brace as well. 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(); I don't like the DoSomething() being on the same line, since that makes it impossible to put a breakpoint on it. * 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. * When calling non-static member functions from another function of the same class or subclass, use "this->". When calling static member functions, you may use "EmMyClass::" to prefix the function call. However, I'm not really sure I like this latter convention, so use the prefix or not, as you choice. * When referencing a data member, you may want to also use the "this->" prefix. I currently don't use this much in Poser, preferring to use the "f" prefix in the data member's name to indicate that it is a data member. However, by using "this->", you can take advantage of VC++'s type-completion features, which I'm finding to be really handy. * 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. * Whitespace. Use lots of it! Vertically and horizontally! It's possible to go overboard -- I knew one programmer who put spaces around every token in his code, leading to stuff like: if ( myPtr -> mySubStruct . myField ) { for (ii = 0 ; ii < max ; ++ ii) { myObject -> CallSomeFunction ( ii * 2 ) ; } } But this is a bit extreme for me. I like putting braces on their own lines for the vertical spacing, spaces in mathematical expressions, and spaces between the function name and following parameter list, as well as the places most other programmers put them. if (myPtr->mySubStruct.myField) { for (ii = 0; ii < max; ++ii) { myObject->CallSomeFunction (ii * 2); } } 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