Chapter 1

3.2.6 Summary
Naming conventions are to some extent arbitrary: the only good thing you can say about
most conventions is that life is better if everybody does the same thing.
But you'll probably have noticed that Symbian OS naming conventions do address one
particular issue: cleanup. That's a key topic, which will be covered in detail in Chapter 6. The
distinction between C and T is fundamental to cleanup. R classes combine aspects of both C
and T. The i prefix for members makes a fundamental distinction that is also cleanuprelated.
And the suffix L on leaving functions indicates functions that may require cleanup.
In other areas, Symbian OS naming conventions are neither worse nor better than anyone
else's. All Symbian OS system and example code uses these conventions (with perhaps a
couple of exceptions in the very oldest code), so your work will be made easier if you use
them too.
3.3 Functions
Function prototypes in C++ header files can convey a lot of information including
� whether it is imported from a DLL (indicated by IMPORT_C), inline and expanded
from a header, or neither of these – that is, the function is private to a DLL;
� whether it is public, protected, or private in the C++ sense (you have to scan up
the file to see this, but it's effectively part of the prototype even so);
� whether it is virtual (you have to scan down the base classes to be sure about this, but
it's part of the signature) – and, if virtual, whether it's pure virtual;
� whether it is static;
� the return type (or void);
� the name – usually a good hint at what the function does;
� whether it can leave (L at the end of the name);
� the type and method of passing for all the arguments (with an optional name that hints
at purpose, though the name is not formally part of the signature);
� whether there are any optional arguments;
� whether it is const.
If a function and its arguments (and class) have been named sensibly and if the right type of
parameter passing has been used, you can often guess what a function does just by looking
at its prototype. For example, the function TInt RFile::Write(const TDesC8&
aBuffer) is the basic function for writing data to a file – you can even guess that TDesC8 is
a type suitable for data buffers by looking at this signature. The TInt return is an error code,
while the aBuffer parameter is a descriptor containing the data and is not modified by the
function.
Most of this is standard C++ fare. The exceptions are leaving functions, which we've already
mentioned (and will explain fully in Chapter 6), and the naming conventions associated with
DLLs. These are very important and aren't covered by C++ standards: I'll cover the
significance of IMPORT_C later in the chapter.
3.3.1 Function Parameters
Each parameter's declaration gives valuable information about whether that parameter is to
be used for input or output and a clue about whether the parameter is large or small. If a
parameter is of basic type X, there are five possibilities for specifying it in a signature: