<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept xml:lang="en" id="GUID-9BADA8E9-15AA-5867-BF14-DB8C4D9B40A6"><title>Naming Conventions</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>Applications on the Symbian platform 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. </p> <section><title>Class names</title> <p>Most class names are formed with a prefix letter <codeph>C</codeph>, <codeph>T</codeph>, <codeph>R</codeph>, or <codeph>M</codeph>. Briefly, the meaning of these is as follows: </p> <ul><li id="GUID-2F4845E7-26DF-585A-A04B-5FA92C602D5D"><p> <codeph>C</codeph>: heap-allocated classes, that are derived from a base class <codeph>CBase</codeph>  </p> </li> <li id="GUID-1769E8BD-E386-59EE-A631-CB2B998812DB"><p> <codeph>T</codeph>: value classes, that do not own any external object </p> </li> <li id="GUID-69F2347E-9CF6-5E56-9124-4D4D2B6B1620"><p> <codeph>R</codeph>: resource classes, that contain handles to a real resource which is maintained elsewhere </p> </li> <li id="GUID-81D42168-744A-55EF-BFD5-13A2E2609CD9"><p> <codeph>M</codeph>: interface classes, that define abstract protocol definitions that are implemented by derived classes </p> </li> </ul> <p>For a detailed discussion on the meaning of these prefixes, see <xref href="GUID-2458916B-55B2-5E08-A825-4EBDB3503E67.dita">Class types</xref>. </p> <p>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. </p> </section> <section><title>Struct names</title> <p>Structure types are considered as similar to <codeph>T</codeph> classes, as they should not own external objects, and are normally given names beginning with <codeph>T</codeph> (although some begin with <codeph>S</codeph>). </p> </section> <section><title>Variable names</title> <p>Member variables’ names begin with <codeph>i</codeph>, e.g. <codeph>iMember</codeph>. This makes it easy to check that certain cleanup-related rules are being obeyed. Arguments’ names begin with <codeph>a</codeph>, e.g. <codeph>aControl</codeph> or <codeph>aIndex</codeph>. Local variables’ names have no initial letter. Global variables are usually avoided, but when used, their names begin with a capital letter. </p> <p>The Symbian platform 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. </p> </section> <section><title>Function names</title> <p>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 <codeph>i</codeph>: </p> <codeblock id="GUID-D2C3445C-50C9-5C11-8D3B-67DE163C9600" xml:space="preserve">inline RWindow&amp; Window() const { return iWindow; };</codeblock> <p>A corresponding “setter” function would include the word <codeph>Set</codeph>, e.g. <codeph>SetWindow()</codeph>. </p> <p>To terminate functions because of error conditions, the Symbian platform does not use standard C++ exception handling, but its own system called leaving (see <xref href="GUID-E5A83EF3-948B-5729-A2CD-3644E803520B.dita">Cleanup Support Overview</xref>). Any function that might leave has a name ending in <codeph>...L()</codeph>. This makes the fundamental process of checking for errors easier. The <codeph>new (ELeave)</codeph> function might also leave. The fundamental leaving function is <codeph>User::Leave()</codeph>. Any function that contains any of these, and does not trap them, might itself leave, and should be coded with a trailing <codeph>L</codeph> in its name. If a function calls another which might leave, then its name should have the <codeph>L</codeph> suffix also. </p> <p>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 <codeph>...LC()</codeph>. For instance, many <codeph>new</codeph>, <codeph>PushL()</codeph>, <codeph>ConstructL()</codeph> sequences are encapsulated in a <codeph>NewLC()</codeph> function: </p> <codeblock id="GUID-51A820E0-923C-5626-A791-7FA0E8F6B6AF" xml:space="preserve">CS* s=CS::NewLC(p1, p2);</codeblock> <p>This allocates the object, initialises it, and leaves it on the cleanup stack. This process may leave (if only through the <codeph>PushL()</codeph> !), so such functions always include an <codeph>L</codeph>, and are therefore <codeph>...LC()</codeph>. </p> <p>A function which takes ownership of its object and destroys it has a name ending in <codeph>...D()</codeph>. An example is the UI framework dialog protocol: </p> <codeblock id="GUID-865E8BED-1C1B-5BC7-A92F-1B5DA6885100" xml:space="preserve">CEikDialog* dialog=new (ELeave) CBossSettingsDialog;

if (dialog->ExecuteLD(R_BOSS_SETTINGS_DIALOG))

    {

    // handle successful settings

    }</codeblock> <p>The <codeph>ExecuteLD()</codeph> function includes second-phase construction, execution of the dialog and then destruction. </p> </section> <section><title>Macro names</title> <p>Macro names are all capitalised, with underscores to separates words. </p> </section> <section><title>Enumeration names</title> <p>Enumerations are named as follows: </p> <ul><li id="GUID-FFB2E991-CB2B-5F95-BF13-E0019EF0FDD8"><p>as enumerations are types, they have the <codeph>T</codeph> prefix </p> </li> <li id="GUID-9E021588-6989-59D7-93D6-6E6B27A88E45"><p>enumeration members have the prefix <codeph>E</codeph>  </p> </li> <li id="GUID-95C953A3-6E0F-5FE2-B357-D1A470DC92E5"><p>type and members should have a meaningful, unambiguous name </p> </li> </ul> <p>Enumerations should be scoped within the relevant class, so as not to pollute the global name space. </p> <p>An example of the declaration and use of an enumeration is as follows: </p> <codeblock id="GUID-035D6258-29BD-5104-A758-81F0C8098DF2" xml:space="preserve">class TDemo

    {

public:

    enum TShape {EShapeRound, EShapeSquare};

    };

TDemo::TShape shape=TDemo::EShapeSquare;</codeblock> </section> <section><title>Constant names</title> <p>Names of constants have a prefix <codeph>K</codeph>. For example, </p> <codeblock id="GUID-4270AB29-EE1F-5DA4-ADA1-16A8DC43A9FC" xml:space="preserve">const TInt KMaxNameLength=0x20;</codeblock> </section> </conbody></concept>