8/4/2019 Coding Conventions 1_6
1/36
EONTechnologies Inc.
Guidelines forEon Technologies Projects
Coding Conventions for C++
Document Version 0.9 Mart 2001
Coding Conventions for C++
1
8/4/2019 Coding Conventions 1_6
2/36
EONTechnologies Inc.
Table of Contents
Guidelines for................................................................................................................1
Eon Technologies Projects...........................................................................................1
Document Version 0.9 Mart 2001.................................................................................1
Table of Contents.........................................................................................................2
Preface.........................................................................................................................3
The Structure of the Document.....................................................................................3
General Guidelines.......................................................................................................4
Standard C++, Win32 and MFC....................................................................................4
Redundant mechanisms...............................................................................................4
The Choice of Names...................................................................................................5
General Conventions....................................................................................................5
Source files...................................................................................................................5
Portability issues.......................................................................................................5
Data Types...................................................................................................................6
Classes.....................................................................................................................6
Structures, Enumerations, Typedefs.........................................................................7
Named values of enumeration...................................................................................7
Variables.......................................................................................................................8
Common variables....................................................................................................8
Global variables.........................................................................................................8
Member variables......................................................................................................9
Arrays........................................................................................................................9
Preprocessor..............................................................................................................10Required preprocessor checks in header files.........................................................10
Methods (functions)....................................................................................................11
Shape of Code............................................................................................................12
The Use of Operators.................................................................................................13
Identing Code.............................................................................................................14
Sequence of Declarations in the Class.......................................................................15
Comments..................................................................................................................15
General Guidelines.....................................................................................................15
Automatic generation of documentation..................................................................16
Scope of commenting.................................................................................................17
Shape of common code comments.........................................................................17
Introduction comment .............................................................................................18
Commenting for autoduck parsing..............................................................................20
Commenting a module (file)....................................................................................20
Commenting a class................................................................................................22
Commenting class functions in detail......................................................................24
Appendix.....................................................................................................................26
A Common Variable Names and Prefixes................................................................26
Common Variable Names.......................................................................................26Prefixes for Variable Types.....................................................................................28
Coding Conventions for C++
2
8/4/2019 Coding Conventions 1_6
3/36
EONTechnologies Inc.
B - Some Programming Styles and Idioms.................................................................31
Do not include header to header when you need a pointer to class........................31
Avoid circular class references................................................................................32
Use of mix in classes and *real* inheritance...........................................................33
Error Handling.........................................................................................................34
Smart stacked variables..........................................................................................36
PrefaceThis document provides conventions for writing C++ code. Coding conventions
described here should be adopted when creating, changing and refactoring the C++
code for Eon Technologies. Conventions are separated to two groups:
Requirements and
Recommendations.
There are only handful basic requirements, which you are required to follow. They werecarefully chosen not to affect the productivity. The objective for the requirements is to
ensure basic unique shape of all the C++ code, produced by or for Software System
Solutions.
As a foil to requirements, recommendations are not "de iure" standard, but selected best
current practices. You are free to make your own decisions about them. You are free to
ignore them where they would impose limitations and/or any kind of penalties to your
efficiency. The objective of recommendations is to promote coding styles, based on
experience, idioms and patterns that could be described preventive and lead to
concise, solid and reliable code.
Coding conventions are a living language. As programming knowledge will grow new
idioms will find their way into this document. Therefore it is by no means thought of as
complete. If you find out new facts or have an idea about how to improve it, you are
encouraged to come forward with your proposals for improvements.
The Structure of the Document
The document is structured into five main parts.
General Guidelines,
Choice of Names,
Shape of Code,
Comments and
Appendix.
General Guidelines chapter discusses latest development in C++ and MS community
and about evolution of C++ programming in general. Choice of Names chapter
prescribes naming for variables, methods, classes, enumerations, structures, file
naming conventions and conventions about naming other elements of C++ source.
Shape of Code chapter prescribes spacing and line breaking in your code. Comments
Coding Conventions for C++
3
8/4/2019 Coding Conventions 1_6
4/36
EONTechnologies Inc.
chapter prescribes head and tail for all source files, mandatory and optional comments
and commenting for automatic generation of documentation.
All that is not described in first four chapters is added to the Appendix section.
Each chapter contains a list of guidelines: requirements and recommendations.
Additional notation is used at the left side of the text to present requirements and
recommendations.
at the left side of text block marks requirement section whilst,
marks recommendation section.
General Guidelines
Standard C++, Win32 and MFCIn 1998 C++ was standardized by ANSI. With the standard came conventions that were
used by the contributors to the standard or strong authors in the field of C++:
Stroustroup, Meyers, Lakos
But as C++ was developed as platform independent programming language theseconventions did not take into consideration existing widely spread frameworks and
conventions such as: Win32 conventions used with Win32 API and conventions used
with the Microsoft Foundation Classes framework (MFC in following text).
As C++ projects may vary it is impossible to give guideline about which style to use. So
as a general rule of thumb you are required to adopt the style of your environment if the
environment already provides you with more then 50% of code. For fairly independent
projects or new projects use prescribed style instead.
Redundant mechanisms
MFC and Standard C++ with STL both introduce their own solutions for some commonlyused abstractions in programming:
Container classes (lists, dictionaries, etc.),
RTTI,
Exceptions.
In general you should apply the mentioned rule of thumb.
You are encouraged to use Standard C++, including new powerful features: new
casts, namespaces, templates and the STL...
Coding Conventions for C++
4
8/4/2019 Coding Conventions 1_6
5/36
EONTechnologies Inc.
The Choice of Names
General ConventionsAll names are in English language. Letters of English alphabet and numbers are allowed
in names of all identifiers. Underline symbol (_) is allowed on occasions described by
the conventions.
Source filesIn general a class should be stored in two files. In header file (with .h extension), which
contains declaration of the class and in implementation file (with .cpp extension).
Chosen filenames can follow long filename convention. You are allowed to use basic
letters of English alphabet in names of files. You are also allowed to use numbers,
underline symbol (_) and ONE AND ONLY ONE dot symbol, which must have a function
of dividing the name from the extension. Use of spaces is not allowed in file names.
For line breaking in source files CR+LF combination must be used.
Portability issues
Using prescribed naming convention (including VC++ conventions) will make your files
portable between various platforms (with respect to line breaking characters).
When programming under Windows you MUST use VC++ convention. It
prescribes capitalized words in name.
Samples:UserAuthenticationSystem.cpp // OK, MFC
User Authentication System.cpp // INVALID
user_authentication_system.h // OK, NOT USING MFC
UserAuthenticationSystem.h // OK, MFC
CommonObjectBroker.cpp // OK, MFC
ObjectValidator.cpp // OK
objectValidator.h // OK, NOT USING MFC
It is warmly recommended that you use VC++ file naming conventions on all platforms
for their generality. By following this recommendation problems will be avoided when
unzipping your files on another platform.
Coding Conventions for C++
5
8/4/2019 Coding Conventions 1_6
6/36
EONTechnologies Inc.
Data Types
Classes
The name of the class should be a noun. All words in the class should start with acapital letter. It is good practice to hint a name from which class it is derived in class
name. For example: if we wanted to declare Yes/No dialog, our class name would be
YesNo, but with hint it would beYesNoDialog.
For Windows programming class names MUST be prefixed with C.
Samples:
class CQuitDialog; // OK, WINDOWS SOURCE
class QueueObserver; // OK, NON WINDOWS SOURCEclass CSettingsManager; // OK, WINDOWS SOURCE
In non-Windows sources classes, which are derived from std. library classes, can use
same conventions as the library.
Samples:
class QueueException : public exception; // OK
class queue_exception : public exception; // OK, using std. library convention
class MyList : public list; // OK
Exception are interface classes (also applies to pure virtual classes!) which are
prefixed with capital letter I, since this is commonly accepted standard.
Samples:
class IConnectionPoint
class IUserManager
class IMessageQueue
Coding Conventions for C++
6
8/4/2019 Coding Conventions 1_6
7/36
EONTechnologies Inc.
Structures, Enumerations, Typedefs
When programming in Windows, structures must be prefixed by capital S letter,
typedefs by capital T and enumerations by capital E letter. This way classes,
typedefs, structures and enumerations have consistent naming.
Samples:
class CFile; // OK
enum ETaskType { copyFile, installFile }; // OK, see Named values of enum.
struct SConnectionPort
{
unsigned data:8;
unsigned parity:1;
unsigned control:2;};
typedef SConnectionPort TConnector;
TConnector conr;
Named values of enumeration
Enumerations also have named values. First word of named value should be in
lowercase others should be capitalized.
Sample:
enum ETaskType { copyFile, installFile};
Coding Conventions for C++
7
8/4/2019 Coding Conventions 1_6
8/36
EONTechnologies Inc.
Variables
Common variablesThe name of the variable should describe the intention (purpose) of variable with
respect to name length. Best names are from 8 to 16 characters long and descriptive. If
variable name is composed of many words then all words in variable must be
capitalized.
In addition a name must be prefixed with it's type (Hungarian notation)!
Sample:
int iLinesPerPage;
A list of prefixes for standard C++ types and common Windows types is given in
Appendix A.
If variable is of type custom class then the prefix is optional. It can be composed as two
to three letter abbreviation, it can be generic a or obj prefix or no prefix.
Samples:
CConnection cnPersonDatabase;
CDynamicAllocator DynAllocr;
CActiveFolder objFolder;
CPerson aPerson;
Global variables
Global variables must be prefixed with g_ or gl_.
Samples:
CPermanentConnection gl_cnSettingsDatabase;
CappSingleton g_objApplication;
Coding Conventions for C++
8
8/4/2019 Coding Conventions 1_6
9/36
EONTechnologies Inc.
Member variables
Class and structure member variables should be prefixed or post fixed.
For Windows source class member must be prefixed with m_.
Samples:
// Windows class
class CMyClass
{
int m_iMemberVariable;
char m_cMemberVariable;
}
In non Windows source variable can be prefixed or (recommended, due to compiler's
usage of prefix) post fixed with an underline.
Sample:
// Generic class
class GenericClass
{
int iMemberVar_;
char cMemberVar_;
}
Prefix or postfix notation are both correct for generic classes. It is good to decide for one
in the scope of same file.
Arrays
Array is a special kind of variable. It follows same naming convention. The name of
array must use plural instead of singular.
Samples:
CListarrPersons;
vectorvctCars; // Cars, with optional type prefix
int iSquares[]={1,2,4,8,16,32,64,128};
Coding Conventions for C++
9
8/4/2019 Coding Conventions 1_6
10/36
EONTechnologies Inc.
PreprocessorYou are discouraged to use preprocessor in all but the following cases:
Conditional compiling and
Include check (for header files).
Instead of macros you should use inline functions and instead of preprocessor constants
you should use namespace constants, class constants or global constants.
Words in preprocessor symbols can be divided by underline symbol. You may prefix
constants with _, to differentiate them from preprocessor macros.
All preprocessor symbols must be capitalized.
Samples:
#define MAX(a,b) (a > b ? a : b)
#define _PI 3.14
#define _MAGIC 1234
Required preprocessor checks in header files
Following preprocessor checks are required in every header file.
Header files MUST test if they were already included using the preprocessor.
MFC header files MUST add directives to enable memory leaks tracing!
Sample:
// MFC directives
#ifdef _DEBUG
#undef THIS_FILE
static char THIS_FILE[]=__FILE__;
#define new DEBUG_NEW
#endif// include test
#if !defined(_OBJBROKER_H)
#define _OBJBROKER_H
... body of objbroker.h file ...
#endif
Coding Conventions for C++
10
8/4/2019 Coding Conventions 1_6
11/36
EONTechnologies Inc.
Methods (functions)First letter of every word in global as well as member method name must be
capitalized.
First word in method should be a verb explaining what the method does. Further text
can contains nouns on which method operates.
Samples:
GetUserInfo(LONG lUserObjectID);
DeleteAll(void);
A special kind of method is method returning Boolean value. This method can start withprefix is.
Samples:
IsValidZipCode(...);
IsEmpty(...);
Coding Conventions for C++
11
8/4/2019 Coding Conventions 1_6
12/36
EONTechnologies Inc.
Another special type of methods worth mentioning are get/set methods for accessing
class properties. As guideline (but broken in MFC and thus optional) class properties
(variables) should be private and only accessible trough get/set methods.
Sample:
class CItem
{
private:
CString m_sDisplayName;
public:
CString DisplayName(); // get method
void DisplayName(CString sDisplayName); // set method
}
The second way is to add noun Get and Set in front of the property name.
Sample:
class CItem {
private:
CString m_sDisplayName;
public:
CString GetDisplayName(); // get method
void SetDisplayName(CString sDisplayName); // set method
}
Note: MFC's CString should be treated as basic type structure.
Private classes as class members are exception to the rule. They should not be
exposed trough get/set properties since that would violate encapsulation. Instead
delegation should be used as access technique.
Sample:
class CItem {
private:
CSubitem m_objSubitem;
public:
DoSomething() { m_objSubitem.DelegatedDoSomething() };
}
Shape of Code
Coding Conventions for C++
12
8/4/2019 Coding Conventions 1_6
13/36
EONTechnologies Inc.
In general preferred way of indenting your code is with spaces instead of tabs since tabs
will not look well (same) on all editors. However due to the fact that many developers
use tabs they are also allowed.
The Use of Operators
Comparison operators, assignment operators, binary operators + and and shiftoperators should be divided from the rest of the code with spaces.
Samples:
if ( a == b ) DoSomething();
b = c;
d
8/4/2019 Coding Conventions 1_6
14/36
EONTechnologies Inc.
Identing CodeCode should be indented by one tabulator (or by four spaces) after each {. It is up to
programmer to decide whether to put { at the end of previous line or at the beginning of
new line.
Recommended bracing style is given in the sample bellow.
Sample:
if ( m_nWatchesNumber < 0 )
m_hResultError = ERROR_EMPTY_WATCHER;
else
{
m_hResultError = ERROR_NO_NOTIFIER;
m_IDs.RemoveAll();
for ( int nCount = 0; nCount < m_nWatchesNumber; nCount++ )
{
if ( m_pWatchNotifier[nCount].GetRegKey() == 1 )
{
m_IDs.Add(m_pWatchNotifier[nCount].GetWatchID());
m_hResultError = ERROR_SUCCESS;
bFilled = TRUE;
}
else
{
m_pWatchNotifier[nCount].SetRegKey(0);
m_bHasZero = TRUE;
}
}
}
Coding Conventions for C++
14
8/4/2019 Coding Conventions 1_6
15/36
EONTechnologies Inc.
Sequence of Declarations in the ClassInside the class the following sequence of declarations (based on protection level)
should be used:
Public members,
Protected members,
Private members.
Within one level of protection the following sequence should be used:
Constructors, destructors
Attributes, properties
Operations
Overridables
Implementation
Sample:
class MyClass
{
public:
MyClass(void); // ctor
virtual ~MyClass(); // dtor
protected:
int _iSomeMember; // attribute
virtual void ExecuteOperation()=0; // overridable
private:
bool _bPrivate; // attribute
void DoSomething() { // implementation
Something();
}
}
Comments
General GuidelinesC++ notation with two slashes should be used instead of the old C notation. There is no
general rule for how much commenting is necessary. Rule of the thumb is that for every
four lines of code there is a need for a line of comment.
This rule should not however support sloppy coding. Code should be written in
concise way, expressive names used to demonstrate intentions. If at some time
some code needs excessive commenting then it should instead be refactored tobe self-explaining.
Coding Conventions for C++
15
8/4/2019 Coding Conventions 1_6
16/36
EONTechnologies Inc.
Automatic generation of documentation
Special tags can be used inside comments, which enable the Autoduck software tool
creating documentation from comments by parsing source code.
Autoduck software is a powerful command line tool that can be used to create
customized HTML, Windows HELP and RTF format documentation of code. The powers
of autoduck are:
Templates for documentation are fully customisable,
Documentation can be created during the build process by adding several
commands to the makefile or adding post-build steps to IDE (for example a
batch file running autoduck and copying documentation to appropriate
directory).
By using Autoduck with it's search and indexing mechanisms there is no need for
additional code documentation beyond detailed design document since all
documentation is created directly from source code by every build.
Proposed procedure for commenting the code is:
1. Write the module.
2. Test it.
3. And only after you have a candidate for review (i.e. 1.0) comment it.
This way no excessive changes will be needed to comments as you change the code
during development.
Coding Conventions for C++
16
8/4/2019 Coding Conventions 1_6
17/36
EONTechnologies Inc.
Scope of commentingFollowing should be commented in source code:
All interfaces to the outside world!,
Most classes, especially classes that will interact with other people's code, by
documenting in detail: class purpose, properties and methods,
All functions that are visible beyond the scope of a file in which they are
declared,
Data structures,
Special algorithms used in class (at the top of file),
All files (by attaching special comment at the top),
common code (hint: control statements)
Every source file (every header file and every implementation file) must also have an
introduction comment explaining basic information about the file.
Shape of common code comments
Line should be commented at it's end, if possible subsequent comments should be
indented.
Sample:
DoSomething(); // now do something
SoSomethingElse(); // now something else, idented
If comment can't be written in one line it should be written in many lines and idented.
Sample:
DoSomething(); // comment for single line of code stretching over
// multiple lines
In case line or comment is too long to be in the same line then comment should be
written at the top of code indented with it.
Sample:
for (int i = 1; i < 100; i++)
// comment for code following
DoSomethingVeeeeeeeeeeeeeeeeeerrrrrrryyyyyyyyyyLooooooooonnnnnnng();
Coding Conventions for C++
17
8/4/2019 Coding Conventions 1_6
18/36
EONTechnologies Inc.
Introduction comment
Top of source file
At the top of every C++ file there should be a heading with the following
information:
//////////////////////////////////////////////////////////////////////
//
// @doc
//
// @module objbroker.cpp ObjectBroker implementation. |
//
// This file implements ObjectBroker class. ObjectBroker class takes
// care for persistence of all objects, derived from PersistentObject.
// It provides base mapping mechanisms. Brokers for different mappings
// should use this class as base class and derive from it.
//
// Example:
// class RDBObjectBroker : public ObjectBroker relational database
// mapper
//
// Copyright 2000 Eon Technologies,
// All Rights Reserved.
//
// Feb the 12th Leonid Doe ([email protected])
// 1.0 Unit has been created and tested.
// Feb the 16th Willy Markwald ([email protected])
// 1.1 Added Seek method to the class. Tested.
//
// NOTE:
// Special algoritm used...//
//////////////////////////////////////////////////////////////////////
Some revision control systems add changes to module automatically by providing tags
such as $Log:$ in the head of file. However since revision control system has not been
chosen yet versioning has to be done manually.
Coding Conventions for C++
18
8/4/2019 Coding Conventions 1_6
19/36
EONTechnologies Inc.
Bottom of source file
Last three lines of file must be:
//////////////////////////////////////////////////////////////////////
// end of objbroker.cpp
//////////////////////////////////////////////////////////////////////
Coding Conventions for C++
19
8/4/2019 Coding Conventions 1_6
20/36
EONTechnologies Inc.
Commenting for autoduck parsingAutoduck comes with sample files and help so no in depth explanation of autoduck is
given here. However basic conventions about the desired minimum commenting are
given for autoduck.
Very important notice: Commenting or using Autoduck is optional !
Commenting a module (file)
The two tags used for commenting a file are @doc comment and @module comment.
Sample:
//////////////////////////////////////////////////////////////////////
//// @doc
//
// @module User.h - User class definition. |
//
// This file defines the user class. This class is used as authentication
// object for the user.
//
// Copyright 2000 Eon Technologies,
// All Rights Reserved.
//
// Feb the 16th Stilian ([email protected])
// 1.0 Tested and released.
//
// NOTE:
// /
//
//////////////////////////////////////////////////////////////////////
The one of importance is the module tag. It accepts two entries following it. The abstract
and the description, divided by a standard autoduck separator |.
Coding Conventions for C++
20
8/4/2019 Coding Conventions 1_6
21/36
EONTechnologies Inc.
The result of the upper code after parsed with autoduck is a new entry under modules
section of documentation:
Module User.cpp - User class implementationFilename: C:/JOB/EON/AUTODUCK/TEST/USER.CPP
DescriptionThis file implements the user class. This class is used as authentication object forthe user.
Copyright 2000 Eon Technologies, All Rights Reserved.
Feb the 16th leonid ([email protected]) 1.0 Tested and released.
NOTE: /
Coding Conventions for C++
21
8/4/2019 Coding Conventions 1_6
22/36
EONTechnologies Inc.
Commenting a class
You comment a class by using several tags that the Autoduck software supports.
Depending on desired level of detail, you might want to comment only header file
definition or you might also comment implementation. .
First part of commenting a class is commenting class definition (inside header file). The
following example demonstrates desired tags for creating EON compliant documents:
// @class User | User authentication object. User must own this object
// to enter the system.
// @base public | Person
class User : public Person
{
//@access Public members.
public:
//@cmember Constructor.
User();
//@cmember Destructor.
virtual ~User();
//@cmember Sets login name.
void Login(std::string sLogin);
//@cmember Gets login name.
std::string Login(void);
//@cmember Sets password.
void Password(std::string sPassword);
//@cmember Gets password.
std::string Password(void);
//@access Private members.
private:
//@cmember User password.
std::string _sPassword;
//@cmember Login name of the user.
std::string _sLogin;
};
The tags uses are @class descriptor, @access descriptor and @cmember (class
member) descriptor. These tags all describe the code that follows and must be put
directly preceding it or else will be ignored or error reported.
After parsed with autoduck the output is:
Coding Conventions for C++
22
8/4/2019 Coding Conventions 1_6
23/36
EONTechnologies Inc.
User Classclass User: public Person
User authentication object. User must own this object to enter the system.
Defined in: C:/JOB/EON/AUTODUCK/TEST/USER.HClass MembersPublic members.
User()Constructor.
virtual ~User()Destructor.
void Login(std::string sLogin)Sets login name.
std::string Login(void)
Gets login name.void Password(std::string sPassword)
Sets password.
std::string Password(void)Gets password.
Private members.
std::string _sPasswordUser password.
std::string _sLoginLogin name of the user.
Commenting template classes is described in autoduck documentation.
Commenting important functions of the class can go to details (commenting each
parameters). Same is possible for commenting enumerations.
Coding Conventions for C++
23
8/4/2019 Coding Conventions 1_6
24/36
EONTechnologies Inc.
Commenting class functions in detail
Class functions can be commented as details of class or as separate topics. They can
be commented in header or in implementation file. Sample bellow demonstrated the
usage of @cmembertag for short descriptions in header file.
For longer function description one can use tag @mfunc (member function). This
should be used on non-trivial functions.
Sample:
// code inside of User class
//@mfunc string | User | Login | This function gets the
//login name for the user object.
std::string Login(void);
Result:
User::Loginstd::stringUser::Login(void)
This function gets the login name for the user object.
Defined in: C:/JOB/EON/AUTODUCK/TEST/USER.H
For even more details one can use separate comment in implementation (cpp) file in
front of function body.
Coding Conventions for C++
24
8/4/2019 Coding Conventions 1_6
25/36
EONTechnologies Inc.
Following sample demonstrates usage of detailed description in implementation file.
Sample:
////////////////////////////////////////////////////////////////////////
// @mfunc This function sets user object login name given by parameter
//
.
//
// @parm string | sLogin | Specifies new login name.
//
// @rdesc Function returns no value.
//
// @ex The following example demonstrates how to use the function: |
// string sLogin="Tomaz";
// User aUser;
// // set user login name
// aUser.Login(sLogin);
//
// @todo Nothing to do. But a nice tag demonstration.
//
//////////////////////////////////////////////////////////////////////
void User::Login(string sLogin)
{
_sLogin = sLogin;
}
Coding Conventions for C++
25
8/4/2019 Coding Conventions 1_6
26/36
EONTechnologies Inc.
Result:
User::LoginvoidUser::Login(stringsLogin)
This function sets user object login name given by parametersLogin.
Defined in: C:/JOB/EON/AUTODUCK/TEST/USER.CPP
Return ValueFunction returns no value.
ParameterssLogin
Specifies new login name.
ExampleThe following example demonstrates how to use the function:
string sLogin="Tomaz";User aUser;
// set user login name
aUser.Login(sLogin);
To DoNothing to do. But a nice tag demonstration.
Appendix
A Common Variable Names and Prefixes
Common Variable Names
Following is a list of names commonly used in programs. The ? in front of the name
stands for Hungarian notation prefix and depends on the type of variable.
Common names for variablesnFirst Index of the first element in the field, pFirst for STL iteratorsnLast Index of the last element in the field, pLast for STL iterators?Sum Sum of elements, the ? is prefix based on type, for example fSum,
nSum, lSum?Avg Average?Max Maximum value
?Min Minimum valuenNum Number of data, can be lNum if LONGnLength The length of field, list, set?Next Index OR value of next element in the set?Prev Index OR value of previus element in the set?Cur Index OR value of current element in the set?Save Saved value?Tmp Temporary value?Src Source, in comparision and transfer routines?Dst Destination, in comparision and transfer routines
Samples:
Coding Conventions for C++
26
8/4/2019 Coding Conventions 1_6
27/36
EONTechnologies Inc.
dSum=0L;
nNum=0;
pFirst=list.begin();
for (pCur=pFirst; pCur=list.end(); pCur++) {
dSum+=*pCur;
dTmp=*pCur; // whatever we need this for...
nNum++;
}
dAvg=dSum/static_cast(nNum);
Coding Conventions for C++
27
8/4/2019 Coding Conventions 1_6
28/36
EONTechnologies Inc.
Prefixes for Variable Types
The following table is a list of prefixes according to the Hungarian notation.
Standard C++ types
C++ typeschar chint nlong lboolean bpointer pvoid v (pointer to void pv)float f double dunsigned u (optional)object a, obj (optional)
string s, str enum efunction fn
Samples:
char * pchName; // correct
char * szName; // also correct
char * pszName; // problematic, since it is not consistent but correct
boolean bFlag;
unsigned long ulValue, lValue2; // both correct, u is optional
void * pvMemBlock;
CPerson aPerson;
CCar objCar;
Coding Conventions for C++
28
8/4/2019 Coding Conventions 1_6
29/36
EONTechnologies Inc.
Common Windows Types
Common Windows typesLPTSTR sz or lpszLONG l
WORD wDWORD dwHANDLE hPOINT ptSIZE sizeRECT rectBOOL bUINT n
Samples:
LPTSTR szUserName;
LONG lVal;
DWORD dwBytesRead;
SIZE size;
RECT rectClient;
UINT nCur;
Common MFC Types
Common MFC typesCString s, str CRect rctCDC dcCRegion rgnCWindow wndCView vwCSize sizControl ctr
Samples:
CString sUserName;
CDC *pdcClient;
Coding Conventions for C++
29
8/4/2019 Coding Conventions 1_6
30/36
EONTechnologies Inc.
Resource Types
Resource typesIDC_ Control within dialog
IDS_ StringIDR_ Multiple valued resource (i.e. MFC doc-view app has shared menu+stringtable resource value)
IDB_ BitmapIDC_ Cursor (not within dialog)IDI_ IconIDD_ DialogHIDD_ Dialog resource help contextHID_ Command help contextID_ CommandIDP_ Message box promptHIDP_ Message box help context
Samples:
IDS_FILE_NOT_FOUND
ID_FILE_OPEN
IDC_EDIT_USERNAME
IDC_CBO_USERGROUP
IDB_COMPANY_LOGO
Coding Conventions for C++
30
8/4/2019 Coding Conventions 1_6
31/36
EONTechnologies Inc.
B - Some Programming Styles and IdiomsUsage of following styles and idioms is optional. This section is composed mostly of personalopinions of people in EON. You are encouraged to contribute your tips and tricks of more effectiveprogramming.
Do not include header to header when you need a pointer to class
Typically whenever you use a class in implementation file you include it in header file.
However, this is not always necessary. Sometimes it adds to long compile times. Here is
an advice how to cut down compile time.
Following is a typical code fragment in header file:
#include "Person.h"
class Task {
private:
Person* _ResponsiblePerson:
}
In this situation the compiler needs not to calculate the size of Person to reserve space
for it inside the class since it only reserves space for pointer. And it knows the pointer's
size. Hence you do not need to include the Person header file. You just need to declare
the name. The same is true for the reference (&) since the reference is nothing more
than constant pointer.
The code can be rewritten as:
class Person;
class Task {
private:
Person* _ResponsiblePerson:
}
By including person.h only to implementation (.cpp) file you effectively assist the
compiler in pre-compilation of header files.
Coding Conventions for C++
31
8/4/2019 Coding Conventions 1_6
32/36
EONTechnologies Inc.
Avoid circular class references
Circular referencing happens when a class references class that refences another class
that references the first class. It can be direct (involving just two classes) or indirect
(circular over many classes). It makes hierarchical unit testing difficult. Instead of writinga simple test program for bottom units and then building further integration tests on
dependencies to already tested units you have to test every class in environment of
untested dependent classes.
O b j e c t 2 O b j e c t 3O b j e c t 1
Figure 1. - Indirect circural dependencies between classes
Coding Conventions for C++
32
8/4/2019 Coding Conventions 1_6
33/36
EONTechnologies Inc.
Use of mix in classes and *real* inheritance
We strongly recommend against using multiple inheritance.
One should differentiate between true implementation inheritances and mix in classes
(interface inheritances). Implementation inheritance should rarely derive from more then
one class. Implementation inheritance translates to IS-A relationship.
Sample:
class Person {
};
// user is a person with login and password
class User : public Person {
string sLogin_;
string sPassword_;
};
Mix in class is a pure virtual and is a technique used to "demand" interface from certain
class. It should be recognizable by class name which should not be a noun but instead
behaviour descriptor (an adjective), such as: Serializable, Persistent, Listable,...
Sample:
// listable is an interface, not a class
class DynamicallyCreatable {
virtual void Create()=0;
}
// using mixin instead of real inheritance
class Person : public User, public DynamicallyCreatable {
// this class is forced to implement interface DynamicallyCreatable
// i.e. the method Create()
}
A rule is that first inheritance is *real* inheritances and follow inheritances are mix-ins.
Sample:
class User : public Person, public DynamicallyCreatable, public Persistent {
}
Coding Conventions for C++
33
8/4/2019 Coding Conventions 1_6
34/36
EONTechnologies Inc.
Error Handling
For error handling inside C++ exceptions should be used rather then return codes from
functions. This technique is optional.
Exceptions
Exceptions are powerful and structured mechanism that makes your code concise and
easier to understand. Here is an example of code that does not use exceptions:
void fn1() {
if (fn2()) {
ok();
} else {
ReportError();
}
}
boolean fn2() {
if (fn3()==1234)
return true;
else
return false;
}
int fn3() {
if (fn4()!=2)
return 1234;
else
return 4321;
}
int fn4() {
return random()*2+1; // 1 or 2
}
Typically in your program you might have hierarchy of calls. If return codes are used as
mechanism to return errors then checks have to be made throughout hierarchy and
error codes translated several times to come to the top hierarchy.
The situation becomes even worse when error handling has to consider other people's
object hierarchies.
Coding Conventions for C++
34
8/4/2019 Coding Conventions 1_6
35/36
EONTechnologies Inc.
With structured exception handling one has ability to catch exception at the desired level
and if it is thrown at the bottom it will be (if not caught) automatically be propagated to
the top level.
Here is an example of preceding code fragment using exceptions.
void fn1() {
try {
fn2();
ok();
}
catch (MyException& e) {
ReportError();
}
}
void fn2() {
fn3();
}
void fn3() {
fn4();
}
void fn4() {
if (random()*2+1 == 2)
throw MyException("Something went wrong");
}
There is however penalty on exceptions. They are C++ mechanism and should not
cross C++ boundaries. When working with COM one should always make sure that all
exceptions are caught and translated to OLE errors before application boundaries are
crossed.
Coding Conventions for C++
35
8/4/2019 Coding Conventions 1_6
36/36
EONTechnologies Inc.
Smart stacked variables
One common technique when using exceptions is to use so-called smart stacked
variables such as auto_ptr (or CComPtr).
The main idea is to put objects on stack by declaring them as private variables. After
exception occurs stack is unwinded and destructors are called. This way objects can
execute the clean up procedures inside their destructors.
An example of smart variable could be transaction processor in following sample.
Sample:
class Transaction {
public:
Transaction();
// intelligence in destructor
virtual ~Transaction() {if (!bCommited_)
Rollback();
}
void Commit();
void Rollback();
private:
boolean bCommited_;
}
You would use this class as follows:
void PerformTransactionedDatabaseOperation() {
Transaction trans;
try {
PerformDatabaseOperation(); // can throw exception
}
catch (DatabaseException &dbe) {
ReportError(dbe);
throw; // propagato to the caller
}
// if exception was thrown function will exit but destructor for
// trans will still be called and transaction will automatically
// rollback.
}