Files

• Use .hxx and .cxx and prefix all header files with "cl".

  • example: clTransaction.hxx, transaction.cxx

• Name major functional blocks cl<FN>Api.hxx

  • examples: clLogApi.hxx, clCkptApi.hxx

    An application only needs to include these files. These files must include any other required header files.

• Other files can be named based on the primary class defined inside

  • examples: clTransaction.hxx

    An application MAY include these files if it wants that specific functionality.

• Internal APIs should be named cl<something>Ipi.hxx

  • examples: clCkptIpi.hxx

    These files may get pulled into application builds due to object containment. However, it must not be necessary for the application program to ever use symbols defined in the Ipi files.

Definitions

• All application-level APIs must be defined under the SAFplus namespace:

  •    1 namespace SAFplus
       2   {
       3   class Checkpoint  // Class
       4     {
       5     ...
       6     }; 
       7 
       8   typedef enum  // Enum
       9     {
      10     LOG_SEV_EMERGENCY = 0x1,
      11     ...
      12     };
      13 
      14   Logger* logInitialize(void);  // A function
      15 
      16   int logSeverity;  // A Variable
      17   };
    

• All internal APIs must be defined under the SAFplusI namespace (I for internal):

  •    1 namespace SAFplusI
       2   {
       3 
       4   };
    

• Do not hide implementation using handles.
  • Expose them via pointers or containment. This makes debugging much simpler and its easy enough just to skip over tracing through the implementation if needed. Also, prefer containment; do not use pointers rather than containment just to hide implementation.

    Example: clSvcIpi.hxx

       1   namespace SAFplusI
       2   {
       3     class InternalObject
       4       {
       5       ...
       6       };
       7   };
    

    clSvcApi.hxx

       1   #include <clSvcIpi.hxx>
       2   namespace SAFplus
       3   {
       4     class Svc
       5       {
       6       ...
       7       InternalObject& getIo(char* key);  // WRONG: InternalObject is exposed to the application so should be in the API, not IPI.
       8 
       9       protected:
      10       InternalObject array[20];
      11       };
      12   };
    

    Note that in this case, the application will end up including the Ipi file. This is ok, it is clear by the namespace what is API and what is internal.

    Example: With pointers, predeclarations are preferred

       1 namespace SAFplusI
       2   {
       3     class InternalObject;  // Predeclaration
       4   };
       5 
       6 namespaces SAFplus
       7   {
       8     class Svc
       9       {
      10       ...
      11       protected: 
      12       InternalObject* array;
      13       };
      14   };