File types

File name extensions

The following file name extensions are used for source and binary files:

C++ header file (.h)

• Header file comments are written for the user of the module. They are adequate if the test cases for the module can be drawn up on the basis of them; see the section Commenting Conventions.

• Write one class in one header file. Only tiny helper classes may be grouped together with their "parent" class.

• Add #ifndef CLASSNAME_H and #define CLASSNAME_H statements in the beginning of a header to protect it against multiple includes from other files. This anti-nesting mechanism prevents multiple inclusions of the header files.

• Inside a header file include only those other header files that are required for class definition or to use the class. Do not use #ifndef statements when including other header files.

• Remember to use your own prefix (e.g., CTetrisAppUi) in class names.

• Forward declarations are preferable to #include statements. If the class is accessed only via pointers or references, it should not be included with #include. Including unnecessary header files may very easily increase build time and object file size significantly. Most #include statements are actually unnecessary. It is often adequate to forward-declare the class.

Wrong:

// MyClass.h
// This pollutes include-hierarchy:#include "OtherClass.h"
class CMyClass: public CBase
   {   
...
private:
       COtherClass* iPointer;
   };

Including "OtherClass.h" is unnecessary, but pollutes the include hierarchy for "MyClass.h". A better solution would be:

Example:

// MyClass.h
class COtherClass;
class CMyClass: public CBase
   {
   ...
private:
    COtherClass* iPointer;
   };

Note that now only "MyClass.cpp" has to include "OtherClass.h". Other modules using just "MyClass.h" never need "OtherClass.h".

• Place constructors and destructors at the beginning.

• Place data members at the end.

• Always use separate sections for derived methods and add comments to describe where they have been inherited from.

• Do not implement inline methods in a header file. Put them into a separate .inl file.

• Use standard headers, giving standard information; be consistent; for example:

// Example.h
// Copyright (c) 2003 Symbian Ltd. All rights reserved.
// Example module header
//

C++ source file (.cpp)

• Implementation file comments are written for the maintainer of the module. They are adequate if they meet the following requirements:

  • They describe class level implementation and clarify all the nontrivial issues

  • Member function comments cover explanations for all the nontrivial implementation code. Other functions must also contain parameter and return value comments.

  • Be consistent in the use of programming conventions.

• Write the implementation of one class in one file.

• Methods should be defined in the same order as in the header file.

• Use the same names for the method parameter as you have used in the header file.

Resource file (.rss)

• Remember all the necessary #includes for your resource structures.

• Use a unique NAME identifier (maximum length is four characters).

• Place enums in .hrh and resource structures in .rh

• Write resource names in lowercase; the resource compiler generates uppercase identifiers for C++ programs automatically.

• Do NOT put strings to be localized into resource files. Use logical names in resource files and put the actual strings in a separate resource header file (.loc), i.e., not to the same header file as resource structures.

• If you are using a TBUFnn variant, e.g., TBUF80 or TBUF64, and you are loading the string into a local TBuf<nn> variable, ensure that both "nn"s are equal. This prevents nasty buffer overflows at run time. The preferred way is to use pure TBUF and use StringLoader::Load or iEikonEnv->AllocReadResourceL methods in your code.

Common header file (.hrh)

• The common header file must meet both C++ and resource file syntax.

• Usually only control IDs, defines, and enums must be placed in the common header file.

• Resource IDs will be collected automatically into filename.rsg and must not be defined in the .hrh file.

• Resource structure definitions must be in the .rh file � they do not meet C++ syntax and thus cannot be compiled by the C++ compiler.

Localization string resource header file (.loc)

• The localization file lists all of the logical names (actually C macros) for texts to be localized.

• Use comments in the .loc file to facilitate easy localization. Comments should be descriptive; describe the functionality of the text item in English.

Project specification file (.mmp)

Extension makefile (.mk)

Extension makefiles can be used where certain build steps that are not catered for by the generated makefiles are required. The makefiles must contain certain make targets. During build activities, abld will call the target corresponding to the build activity that is being carried out. This will then execute the commands that the makefile specifies for that target.

Package file (.pkg)

he native Symbian installation package file format is .sis. The makesis tool uses package files (.pkg) as input for creating .sis files. The .pkgfile is a text file that contains installation information for applications or files.

Inline file (.inl)

Inline functions must be defined in a separate file, that is, not in the header file.