Vulcan Project Rules

Vulcan Rules Version 1.0

  1. Procedure
    1. New code
      1. Major or global changes will be discussed on the developer list prior to implementation and again prior to checkin.
      2. Developers are responsible for fixing all down stream references and procedures affected by their changes.
    2. Code cleanup
      1. All developers are responsible for general cleanup of code in areas in which they work.
      2. All developers are responsible for the paragraphing of code in areas in which they work.
      3. All developers will remove artificial integer types USHORT, SHORT, etc. in areas in which they work.
      4. Pragmas, deliberate errors in platform conditional code, etc. will not be used as placeholders for missing cleanup.
    3. Project architect
      1. The project architect has veto power over all code checkin.
      2. The project architect must explain all exercises of this power to the developer list.
  2. Licenses
    1. All modules currently licensed under IPL must continue to be licensed under IPL
    2. New modules must be licensed under IDPL
    3. No restrictions beyond those of the IDPL may be applied to any modules.
  3. Classes
    1. Encapsulation 1. All new code is encapsulated in classes 2. Existing code will be encapsulated when it is modified
    2. Names
      1. Class names begin with a capital letter.
      2. Class member names begin with a lower case letter.
      3. Underscores are not used in new names
      4. Names use internal capitalization to indicate word boundaries, e.g.DatabaseMetaData.
    3. Declaration files
      1. A class is declared in a file called <ClassName>.h.
        1. A class declaration file contains only one class.
        2. A class declaration file also defines all constants required for that class.
        3. A class declaration file must contain abstract declarations for classes referenced in the declaration
        4. A class declaration file includes class declaration files for classes included as members.
    4. Implementation files
      1. A class is implemented in a file called <ClassName>.cpp.
      2. A class implementation file contains only one class implementation
  4. C++ usage
    1. Deprecated
      1. Use of the C++ std library is deprecated and will be phased out.
      2. C++ template use is discouraged
      3. Use of language features not generally and uniformly implemented across the industry is prohibited.
      4. Multiple inheritance is strongly discouraged except for classes that inherit from the class “RefObject”
    2. All casting is discouraged and should be avoided by consistent type declarations.
    3. Function or class method declarations will not use pass by reference
    4. Macros
      1. The use of macros is generally discouraged, but permitted when necessary to encapsulate commonly used code sequences
      2. Use “static const” to name constant values rather than macros
    5. Prefer switch statements to multiple if statements.
  5. Conditional Compilation
    1. Conditional compilation of specific features is prohibited
    2. Conditional compilation of debugging routines is permitted when appropriate.
    3. Conditional code required for platform specific features will be restricted to modules dedicated to platform services.
    4. Classes should not have conditional compilations for different environments.
  6. Data declarations
    1. The use of 8 and 16 bit integer data is strongly discouraged except where required by ODS and API specifications.
    2. Local variables
      1. Local variables are declared at first use,
      2. Local variables are generally be initialized in their declaration
    3. Character data
      1. Character data will be declared as “char” or “TEXT”.
      2. Characters strings will normally be passed as “const char*” or “const TEXT*”.
      3. Character strings as class members will normally be declared as instances of the string class JString.
      4. No character string declared as “const char*” may be cast to “char*” for the purposed of passing it to a incorrectly declared function for method.
    4. Numeric data
      1. Byte array data will be declared as “UCHAR”.
      2. Numeric values that can be accommodated in 31 bits or fewer will be declared as type "int" unless they are stored in the database or used in the API ,
      3. Signed numeric values that are architecturally constrained to 32 bits will be declared as “SLONG” (deprecated) or “INT32”
      4. Unsigned numeric values that are architecturally constrained to 32 bits will be declared as “ULONG” (deprecated) and “UINT32”.
      5. Signed and unsigned 64 bit numeric values will be declared as “INT64” and “UINT64” respectively.
    5. Pointer to objects will normally not be declared as “const”.
  7. Memory Allocation
    1. Allocation
      1. Objects will be created, in general, with the operator “new”.
      2. Objects are responsible for clearing memory they allocate.
    2. Deletion
      1. All objects will be formally deleted
      2. Objects are responsible for releasing memory and other resources they allocate or control.
    3. Memory pools
      1. The existing memory pool mechanism is deprecated and will be phased out.
      2. Memory pools for placement control will be re-introduced at a future date.
  8. Coding conventions
    1. Developers may use whatever coding conventions they prefer in their working areas, but checked in code must follow these conventions
    2. Indentation
      1. Indentation is four spaces which may be represented by four space characters or a tab character with a width of four spaces
      2. Sub-statements of for, while, if, try, catch, and switch are indented.
      3. Braces are indented with the code they enclose except at the top level.
    3. Comments
      1. Comments will be at the same indentation level as surrounding code.
      2. Block comments at the top of methods and functions will describe the general purpose and algorithm of the method or function
      3. Comments within a method or function will occur before the statement(s) they describe.
      4. If you feel the need to insert a comment inside the condition of a for/while/if/switch statement, reconsider and simplify the condition.
    4. Braces
      1. Matching braces are vertically aligned
      2. Braces are not normally used around single statements, but may be used for clarity
    5. Blank lines
      1. For, while, if, try, and switch statements will normally be preceded and followed by blank lines.
      2. Very simple for and if statements used in inner statement blocks may have blank lines omitted.
      3. Comments will be preceded and followed by blank lines
  9. Proposing extensions to Vulcan
    1. Provide background
      1. Problem to be solved
      2. Applicability any known standards
      3. Solutions used by other products address the problem
    2. Describe solution
      1. Syntax and semantics of proposal
      2. Proposed implementation
      3. Components affected
      4. Backward and forward compatibility
    3. Analyze impact of changes on
      1. External API
      2. Provider API
      3. Wire protocols