PantoMIME: Developer Nomenclature ================================= CVS: $Header: /cvsroot/pantomime/PantoMIME/doc/nomenclature.txt,v 1.6 2002/03/13 08:54:29 menelan Exp $ This document describes the PantoMIME development & source code nomenclauture. ------------------------------------------------------------------------------ INTRODUCTION: The PantoMIME project is, potentially, a long-term one; especially given the current fact that it is a spare-time project amongst a few people. If the project is to be successful, obviously teamwork and communication are essentials. An important part of this is to agree on certain standards and conventions, as this reduces "development entropy"; energy and productivity lost on converting between, and trying to understand, what various personal standards the team members may have. There are, of course, many equally valid ways in which to layout code, name programming constructs, etc. The important thing is not so much which style is agreed upon but the fact that it /is/ agreed upon. :) The following outlines the nomenclature agreed upon for PantoMIME development. While nobody will Find And Kill You if you should stray slightly from these conventions, PLEASE try to follow them as closely as you can! It's really for the best of all of us... :) ------------------------------------------------------------------------------ NAMING CONVENTION: This section describes the naming conventions applied in the PantoMIME code. Generally speaking, symbols (depending on their type) are named in compliance with the following conventions (specified in detail below): meta-prefix(es) + symbol name + meta-suffix(es) Where: symbol name: The purpose of symbols is, obviously, to identify something through a word (or compound). Each word is to begin with a capital letter. E.g. 'Module', 'FileName' or even 'VeryLongSymbolName'. Try to make the symbol as mnemonic as at all possible; don't abbreviate words unless the symbol really becomes excessively long or the abbreviation is an obvious one. meta-prefix: The purpose of "meta prefixes" (i.e. prefixes that tell something /about/ the type or class) is to integrate vital information about a type/class in its name, in order to alleviate the developers' need to look up the original type/class declaration in order to become aware of said information. E.g. 'I', 'A' or 'C'. meta-suffix: The purpose of "meta suffixes" (i.e. suffixes that tell something about the type/class) is to integrate semantic information about a type/class/variable in its name, in order to alleviate the developers' need to look up the original type or class declaration in order to become aware of said semantics. E.g. 'Ptr' or 'Hnd'. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - TYPES (typedef, class, struct, union, enum): "Namespace" Prefix: We do not use namespace prefixes for the types in PantoMIME; instead, we're using namespaces. ALL pantomime classes/types MUST be declared within the namespace: "PantoMIME". Do note, however, that files containing declarations ARE prefixed with an identifier ("mime") in order to prevent file-system clashes with existing files. A file containing declarations for the class "CConcreteClass" would, in other words, be called: "mimeCConcreteClass.hpp". Meta Prefixes: I : Interface; class containing only abstract, pure virtual methods and no attributes (i.e. interfaces in the Java sense). (E.g. IFactory) R : Realisation; concrete class directly implementing some interface(s). (E.g. RFactory) A : Abstract; implementation class containing one or more abstract methods. (E.g. ASharedImplementationClass) C : Class; ordinary implementation class (e.g. CConcreteClass). M : Mix-in (augmenting) class designed to embellish other classes. P : Parameterized class (i.e. a Template, in C++) (E.g. PAutoPtr< CClass > lClassPtr( new CClass() );) S : Structure; simple structure (e.g. SMessage) U : Union; union of structures (e.g. URequest) T : Type; simple type definition (e.g. TUnicodeChar) E : Enumeration (e.g. EMessageType) Meta Suffixes: Ptr : Pointer Ref : Reference Hnd : Handle Hdr : Header Cnt : Count Len : Length Ofs : Offset Pos : Position Num : Number Rng : Range Max : Upper limit Min : Lower limit Lst : Array/vector/list Val : Value Idx : Index value Flg : Flag Sz : Size ID : ID Suffixes like Idx or Pos can have a "0" or "1" base suffix appended to them, indicating whether the type is 0 or 1 relative (a common reason for off-by-one errors is making wrong assumptions about this). For instance, "inHeaderIdx0" tells us that this is an input parameter containing a zero relative header index. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - VARIABLES (globals, variables, attributes): Meta Prefixes: g : Global scoped (outside classes only) (E.g. gGlobalExportedVar) v : File scoped (outside classes only) (E.g. vFileGlobalNonExportedVar) l : Local (stack) variable (both inside and outside classes) (E.g. lListIdx) a : Normal attribute (inside classes only) (E.g. aModuleNum) c : Class (static) attribute (inside classes only) (E.g. cStaticAttribute) m : Structure member (inside structs only) (E.g. mHeadPtr) in : (see arguments, below) out : (see arguments, below) io : (see arguments, below) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ARGUMENTS: Meta Prefixes: in : Input argument (e.g. inNameStr, inNamePSZ, inFileHnd) out : Output argument (e.g. outModulePtr, outNameLen, outSamplePos) io : Input/Output argument (e.g. ioCurrentCRC) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - FUNCTIONS (methods, functions, calls): Meta Prefixes: new : Factory, instantiate (e.g. IHeader *lHeaderPtr = RFactory::newHeader();) get : Accessor, get (e.g. lMessagePtr->getHeader();) set : Accessor, set (e.g. lMessagePtr->setHeader();) can : Capability test (e.g. lWriterPtr->canStreamBinary();) is : State test (e.g. lMessagePtr->isMultipart();) All "actions" (written as verbs) begin with a lowercase letter, just as the meta prefixes. If you, for example have a function that waits for a thread, it would be called: waitThread(); A function saving modules could be called: saveModules(); In other words, functions/methods always begin with lowercase! The exception to this rule class (static) methods; they begin with an upper- case letter rather than a lowercase letter; e.g. GetContext() is a class method, whereas getContext() is a normal method. Meta Suffixes (applicable to query-functions only!): : No suffix; return type is a value/type. Ref : Return type is a reference to a type. Ptr : Return type is a pointer to a type. PSZ : Return type is a pointer to a 0-terminated string. (Special case of the Ptr suffix, used for indicating C strings.) The meta-suffixes listed above are only applicable to query ("getter") functions. I.e. you should ONLY is them for getXXXXX methods... The rationale for appending these suffixes is (1) that function overloads cannot be done on return type in C++ so it is not possible to have more than one method of the same name with the same name; and (2) that it is very useful to the caller to be aware of whether he gets a "Qwe" or a "pointer-to-Qwe" when he calls a getQweXXX() accessor. Also note that protected methods are always prefixed (before any other prefixes) with an underscore ('_'). E.g. "int _getType();"). Private methods are always both prefixed and suffixed (this suffiex goes after any other suffixes) with an underscore. For example: "int _GetTypeID_();" Platform-Specific System Calls: In order to help one identify system/playform API calls (and also to help prevent name clashes with functions in the imported namespaces), these calls are always prepended with the global scope specifier "::". For instance ::DosClose( mConfigFileHnd ); // OS/2 Kernal API ------------------------------------------------------------------------------ INDENTATION: Only use spaces for indentation. Never tabulators. Never. OK? :) ------------------------------------------------------------------------------ COMMENTATION: ;;; doxygen ;;; document interface declarations, not realisation declarations ;;; document what's important, not what's obvious ------------------------------------------------------------------------------ NOTATION: signatures pointers/references breaking of long argument lines void qwe::qwe( int inI, float *fPtr, double &ioD ):parent( inI ), grandparent( ioD ) { if( condition ) { ::SomeSystemCall( os ); } // if } // qwe::qwe() ^^^ Preferred method layout... class qwe: public qwe1, public qwe2, public qwe3 { //--- House Keeping --------------------------------------------------------- public: qwe(); qwe( const qwe &inRef ); virtual ~qwe(); //--- Methods --------------------------------------------------------------- public: ///... protected: ///... //--- Attributes ------------------------------------------------------------ private: ///... }; // class qwe ^^^ Preferred class layout... ------------------------------------------------------------------------------ ------------------------- ------------------------- TEMP: ------------------------- f : Flag (e.g. enum EOpenFlags { fRead, fWrite, fReadWrite }; ) e : Enumeratopm (e.g. enum EOpenFlags { eLow, eMedium, eHigh }; ) k : Constant id : ID (general) res : resource id ;;; msg : Message ID ;;; suffix instead? ;;; res : Resource ID ;;; suffix instead? Variables: Meta Suffixes: The following meta suffixes are currently defined: Ptr : Pointer Hnd : Handle Hdr : Header Str : String (STL class) PSZ : String (C, ASCIIZ) Cnt : Count Sz : Size Len : Length Ofs : Offset Pos : Position - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - VARIABLES (globals, variables, attributes): - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ------------------------------------------------------------------------------ NOTATION: signatures pointers/references void *test( int &ioTst1, int *inTestPtr ); ::OSSystemCall(); suffix indicator for Scoped ("RAII") classes? ------------------------------------------------------------------------------