Slow Control

Coding Standard for CLEO Slow Control

Rules

• Rule 1:

  IDL files are to be treated like header files in C/C++!
  They can be included from other IDL files, so they need protection against multiple usage.

  Always use an IDL file structure like:
  #ifndef [MODULENAME]_[FILENAME]_IDL
#define [MODULENAME]_[FILENAME]_IDL
  ...
  #endif

  MODULENAME should be the name of the library/module this interface is used in, FILENAME should be the filename in which this code is stored.

  Example:
  #ifndef COMSYS_HEARTBEAT_IDL
#define COMSYS_HEARTBEAT_IDL
...
interface heartBeat
...
#endif


• Rule 2:

  The IDL file is processed by the C preprocessor before the IDL to C++/JAVA translation is done!
  On some platforms this is actually the C compiler run with a special option. Sometimes this compiler is confused and is started in C syntax mode.

  All comments must be in C style!

  Example:
  /* The HeartBeat interface implemented by ALL official members of SC */


• Rule 3:

  The IDL file (just as all JAVA and C++ source files) has to contain the RCS id string!

  Use the /*...*/ syntax to enclose this string (according to Rule 2).

  Example:
  /* $Id$ */


• Rule 4:

  The JAVA code will always give the class describing the interface a namespace.
  To avoid the default name `IDLglobal', always use at least one module statement.

• Rule 5:

  You can have more than one interface in a single IDL file, if this structures the use of the object more clearly.
  Remember: Each interface becomes its own class, so each needs a bind call with all the involved overhead!
  Try to find a balance between one bind and 100 methods and 100 binds with 1 method...

  You must not have more than one module per file, if it also includes interface definitions! See Recommendation 1 about a setup of an `interface tree'.

• Rule 6:

  Our CORBA implementation uses `_' internally!
  To avoid unexplainable behaviours, you should avoid `_' in all class and method names!
  C preprocessor symbols are okay, since they disappear from the code with no trace...

  Use the capitalization scheme in Rule 7 to combine words to an identifier.

  Example:
  readonly attribute short HeartBeatIntervall;

• Rule 7:

  Consistent capitalization can help you read code!

  Each (english) word added to another one to form an identifier starts with a capital letter. Do not use `_'!

  Example:
  oneway void oneBeat(in string component);


  • Interfaces: They become classes, so they start with a capital letter.
  • Interface functions: Start with a small letter.
  • Interface attributes: Have the `flavor' of an object and are not behaving like functions. Start the name with a capital letter.
  • Structures and `typedef's: All these items are handled like classes, so their names start with a capital letter
  • Data items in a Structures: Data items should start with a small letter.
  • Enumeration types: Names inside the `enum' list should start with a capital letter.

  Example:
  

  /* Enumeration types */
  enum    Severity       {Info, Warning, Error, Severe, Fatal};
  enum    Granularity    {None, Channel, Card, Board, Crate, Sector, Detector};
  enum    Rule           {NoRule, Default, Pause, Stop, Halt};
  
  /* Granularity number (0 = all) */
  typedef unsigned long  UnitCode;
  
  /* Alarm Identification Number (0 = all) (Better than working with string) */
  typedef unsigned long  AlarmID;
  
  struct AlarmObject
  {
    TimeObject   generatedAt;
    Severity     severity;
    Rule         rule;
    Granularity  granularity;
    UnitCode     unit;
    AlarmID      id;
    string       explanation;
  };
  

• Rule 8:

  Most interface functions represent an action performed on the object implementing the interface.
  If a verb describes this action, use it as the first part of the identifier.

  Interface attributes represent states. They should not contain a verb.

  Example:
  AlarmObjectList dumpActiveAlarms(in string brokerName);

• Rule 9:

  Order the parameters of the interface functions by there flow of information!

  1. `in' parameters.
  2. `inout' parameters.
  3. `out' parameters.

  All parameters should have variable names, that make it easier to understand their meaning.

  Example:

    boolean getTaskName(in taskId id, out string name);
  	

Recommendations

• Recommendation 1:

  Interfaces and data structures defined in IDL are placed into module blocks to create namespaces. Since IDL files are named like the interface they contain, a name clash in the file system is possible.

  Create a directory tree reflecting at least the namespace of the interfaces! (You can spread out things more "finely" if this helps you or makes you feel better...)
  Example:

  .../idl
      |
      +-----> Alarm
      |         |
      |         +-----> AlarmObject
      |         |           |
      |         |           +------> AlarmObject.idl
      |         |           +------> AlarmEnum.idl
      |         |
      |         +-----> AMBroker
      |         .          .
      |         .          .
      |
      +-----> RunControl
      .
      .
  	  

• Recommendation 2:

  To create the complete IDL library (especially for JAVA) we will include all files in the IDL tree (See Recommendation 1) at the root level!

  Create an IDL file in each sub branch, that uses #include to create a single C++/JAVA file from all sub branches underneath it.
  Do not forget Rule 1 for those files!

  For the example from Recommendation 1, we have to create:
  In Alarm: Alarm.idl
  

  #ifndef MODULE_ALARM_IDL
  #define MODULE_ALARM_IDL
   
  #include "TimeObject.idl"
   
  #include "AlarmObject/AlarmObject.idl"
  #include "AMBroker/AMBroker.idl"
  
  #endif
  	

  Where you place the module statement and how nested they are is up to you!

  The example also shows that you can include IDL files not part of this current tree. The command line used to translate the IDL code will have "-I" options switched on, so each branch following the idl root directory is included.

Slow Control