Symbian3/SDK/Source/GUID-9BADA8E9-15AA-5867-BF14-DB8C4D9B40A6.dita
author Dominic Pinkman <Dominic.Pinkman@Nokia.com>
Thu, 21 Jan 2010 18:18:20 +0000
changeset 0 89d6a7a84779
permissions -rw-r--r--
Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
0
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     1
<?xml version="1.0" encoding="utf-8"?>
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     2
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     3
<!-- This component and the accompanying materials are made available under the terms of the License 
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     4
"Eclipse Public License v1.0" which accompanies this distribution, 
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     5
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     6
<!-- Initial Contributors:
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     7
    Nokia Corporation - initial contribution.
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     8
Contributors: 
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     9
-->
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    10
<!DOCTYPE concept
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    11
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    12
<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;
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    13
if (dialog-&gt;ExecuteLD(R_BOSS_SETTINGS_DIALOG))
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    14
    {
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    15
    // handle successful settings
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    16
    }</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
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    17
    {
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    18
public:
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    19
    enum TShape {EShapeRound, EShapeSquare};
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    20
    };
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    21
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    22
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>