Hemelix

Naming convention used in Symbian

Now we have run our HelloSymbian program. We have seen that there a function name LocalMainL(), probably you have thought why there is L at the end of this function? This is about naming convention, for this case, at the end L means it might leave (means this function might throw exception see more from here). This is about naming convention in Symbian. Without this compiler will not complain but it is easier to understand, maintenance source code. With this example with L, when we use such function then we can think that inside this function it might leave. So we need some special treatment for this. What kind of treatment is available, you can find it from cleanupstack chapter.)
Rationale for Symbian coding convention.

• provide common syntax for Symbian OS C++
• help reinforce Symbian OS programming idioms
• help communicate Symbian OS C++ class design for APIs
• serve as checklist for coding
• act as reference during code inspection/review
• helps produce efficient and reliable code for ROM-based devices

• typedefs of built-in types for integer, floating-point, character, and pointer types ( e32def.h ), compiler-independent.


• TInt, TUint
  signed and unsigned 32-bit integers


• TBool
  values ETrue (=1) and EFalse (=0)


• TReal
  Double precision (64-bit) floating point number


• TText
  Build independent general text character, In non-Unicode builds, this is mapped to TText8. In Unicode builds, this is mapped to TText16.


• TAny*
  Pointer to anything (use instead of void*)

Symbian OS Classes

• Classes should have a clear role


• One class to one header file (the ideal)


• Layout of header files:
  #include files; friend classes; public, protected, private methods; private, protected, public data.


• T-, C-, M-, R- convention to denote different class types

Now let's take a closer look in each type of classes in following section.

T Classes

• Behave like C++ built-in types


• No destructor => can be created on the stack and will be cleaned up correctly when the scope of function exits


• Contain member data which is:
  -Built-in types
  -Pointers and references with uses a relationship


• Contain all data internally


• Example:
  class TInitParams {
  public:
  TInt iN1;
  TInt iN2;
  }

C Classes

• CBase ( defined in e32base.h ) is the base class for all C classes.


• All C objects are allocated on the heap.


• When it is first allocated on the heap all member data will be zero-filled


• When no longer needed heap-based objects must be destroyed


• It has a virtual destructor (destroyed properly by deletion through a CBase pointer)


• Example:
  
  class CExample : public CBase
  {
  ...
  }
  
  CExample* myExample = new(ELeave) CExample;
  .
  .
  .
  delete myExample;
  

• R classes are proxies for objects usually owned elsewhere.


• There are two main motivations for this,
  - the real object is owned by a server in a different thread or address space
  -implementation of real object must be hidden from the client.


• There is no common base class for all R classes.


• The initialization function has a variety of names, like Open(), Create(), Allocate(), etc.


• The termination function has a variety of names, like Close(), Destroy(), Free(), etc.


• Example:
  RTimer myTimer;
  RFs myFileServerSession;
  RWsSession myWindServSession;
  
  // e.g.
  myTimer.CreateLocal();
  .
  .
  .
  myTimer.Close();
  

• The only form of multiple inheritance allowed by Symbian OS is where the extra classes are Mixins.


• Mixins (M classes), define an interface but do not provide an implementation of it


• they do not have any data members.


• only pure virtual functions


• A concrete class derived from a Mixin must implement its interface.


• Example:
  class MRadio
  {
  public:
  virtual void TuneL() =0;
  };
  
  class MClock
  {
  public:
  virtual void CurrentTimeL(TTime& aTime) =0;
  };
  
  class CClockRadio : public CBase, public MRadio, public MClock
  {
  public:
  void TuneL();
  void CurrentTimeL(TTime& aTime);
  };
  

• Data members: use prefix i -, should be private


• Arguments: prefix a-


• variables start with lower case, Functions Start With Capitals


• Setter functions: SetThing(aThing);


• Getter functions: myThing = Thing(); (return it)
  GetThing(myThing); (pass it by ref.)


• Variables including arguments: & for uses-a and * for has-a


• Trailing L,C for functions that cause exceptions (L means leave function, LC means it may leave and the function keep object on cleanupstuck)


• Trailing D for functions that delete object

Now we know basic of Symbian naming convention. Let's download sample example from following link and browse/run in our carbide.