Applications on Symbian OS use a standard set of conventions to name their classes, structs, variables, functions, macros, enumerations, and constants. This topic explains the meaning of these conventions.
Most class names are formed with a prefix letter C
,
T
, R
, or M
. Briefly, the meaning of
these is as follows:
C
: heap-allocated classes, that are derived from a
base class CBase
T
: value classes, that do not own any external
object
R
: resource classes, that contain handles to a
real resource which is maintained elsewhere
M
: interface classes, that define abstract
protocol definitions that are implemented by derived classes
For a detailed discussion on the meaning of these prefixes, see Class types.
Classes that consist solely of static member functions have no prefix letter. Beyond the prefix, the class name is usually a noun that indicates the purpose of the class.
Structure types are considered as similar to T
classes, as they should not own external objects, and are normally given names
beginning with T
(although some begin with S
).
Member variables names begin with i
, e.g.
iMember
. This makes it easy to check that certain cleanup-related
rules are being obeyed. Arguments names begin with a
, e.g.
aControl
or aIndex
. Local variables names
have no initial letter. Global variables are usually avoided, but when used,
their names begin with a capital letter.
Symbian OS does not use Hungarian or any notation which attempts to include the variable type in its name: such notations are ugly, and become impossible to manage when there are several hundred classes in the system. They are irrelevant anyway: functions are usually so short that it is easy to see the types of variables defined in them, and class browsers provide a quick way to find the types of class members.
Functions names indicate what they do. They are usually
verbs. One exception is getter functions: for a function
which returns the value of a member variable, the function name is usually the
name of the variable, without the leading i
:
inline RWindow& Window() const { return iWindow; };
A corresponding setter function would include the
word Set
, e.g. SetWindow()
.
To terminate functions because of error conditions, Symbian OS does
not use standard C++ exception handling, but its own system called leaving (see
Cleanup Support Overview). Any function that might leave has a name ending in
...L()
. This makes the fundamental process of checking for errors
easier. The new (ELeave)
function might also leave. The
fundamental leaving function is User::Leave()
. Any function that
contains any of these, and does not trap them, might itself leave, and should
be coded with a trailing L
in its name. If a function calls
another which might leave, then its name should have the L
suffix
also.
Associated with the leaving mechanism, is the cleanup stack, which
allows memory allocated on the heap to be recovered when a leave occurs. An
allocation or construction function which places data on the cleanup stack ends
with ...LC()
. For instance, many new
,
PushL()
, ConstructL()
sequences are encapsulated in a
NewLC()
function:
CS* s=CS::NewLC(p1, p2);
This allocates the object, initialises it, and leaves it on the
cleanup stack. This process may leave (if only through the
PushL()
!), so such functions always include an L
, and
are therefore ...LC()
.
A function which takes ownership of its object and destroys it has
a name ending in ...D()
. An example is the UI framework dialog
protocol:
CEikDialog* dialog=new (ELeave) CBossSettingsDialog;
if (dialog->ExecuteLD(R_BOSS_SETTINGS_DIALOG))
{
// handle successful settings
}
The ExecuteLD()
function includes second-phase
construction, execution of the dialog and then destruction.
Enumerations are named as follows:
as enumerations are types, they have the T
prefix
enumeration members have the prefix E
type and members should have a meaningful, unambiguous name
Enumerations should be scoped within the relevant class, so as not to pollute the global name space.
An example of the declaration and use of an enumeration is as follows:
class TDemo
{
public:
enum TShape {EShapeRound, EShapeSquare};
};
TDemo::TShape shape=TDemo::EShapeSquare;
Names of constants have a prefix K
. For
example,
const TInt KMaxNameLength=0x20;