LFC Coding Style

LFC Coding Style

Leonard Mosescu
(lemo@metasoft.ro)

Contents

1 Introduction
   1.1 Formating tools
   1.2 Conventions
2 General guidelines
3 Identifiers naming
   3.1 Variables names (global, member, auto, ...)
   3.2 Types (class, enum, typedef)
   3.3 Functions (global, methods, ...)
   3.4 Constants
   3.5 Namespaces
4 Source code organization
   4.1 Source file names
   4.2 Location (hierarchical structure)
   4.3 Source file structure
     4.3.1 C++ headers
     4.3.2 C++ sources
     4.3.3 C++ inline sources
5 Comments
6 Indentation guides
7 Functions (methods)
8 Classes
   8.1 General class formatting guidelines
   8.2 Class templates
   8.3 Special class members
   8.4 Multiple base classes and LFC ’interfaces’
9 C++ statements
   9.1 If (if...else if...else)
   9.2 Switch
   9.3 While, do..while, for
   9.4 Try..catch
   9.5 Goto
10 Declarations, expressions
11 Spacing

1 Introduction

This document describes the official LFC guidelines for writing/formatting C++ code. It is intended to help LFC developers in order to ease the creation of high quality, easy to read code.

These guidelines don’t bring immediate advantages in code speed/memory usage, neither do they guarantee high quality code. But the benefit of following these guidelines is at least as valuable: we’ll get clean, readable code that is easy to maintain and allows for extension. That is vital for a team!

As you may know, there are quite a few C++ coding styles out there. Every good team and programmer follows a coding style. There are not many objective arguments to compare different coding styles, and to decide that one style is better than another, and in any case, any style is better than no style. So the style presented here makes no claims to be better than other styles, it’s a style on which LFC developers agree on; it tries to offer a set of guidelines to unify the way code ’looks’ across the project, without placing a burden on the programmer.

The basic goal for LFC code regarding coding style is that all of the LFC code should use the same style (as opposed to: ’this is my module, I’ll just use my own style’).

This document will try to cover most of the coding style issues, but at the same time it should be reasonably brief, so it can be easy to use, by avoiding to list hundreds of pages with all the cases and details. When in doubt, take a look at the code already written and/or ask for advice from the other team members (and if it’s the case, update this doc).

If your code doesn’t look like the rest of LFC code or if other members are having trouble reading it, then consult this doc and update your code.

Happy coding!

1.1 Formating tools

There are various tools that can auto format source code to one or more coding styles. While those tools are useful to format external code (from other projects, etc.), the new code should be written from the start to conform to the coding style.

1.2 Conventions

In this document there will be examples of code. The good formatting example will be green and the bad formatting will be red.

2 General guidelines

3 Identifiers naming

3.1 Variables names (global, member, auto, ...)

3.2 Types (class, enum, typedef)

3.3 Functions (global, methods, ...)

3.4 Constants

3.5 Namespaces

4 Source code organization

4.1 Source file names

4.2 Location (hierarchical structure)



LFC core headers core/include


LFC core sources core/src


LFC core inline sources core/include/inline


PAL headers core/include/platform (platform is win32 or posix)


PAL sources core/src/platform (platform is win32 or posix)


Samples samples/sample


Tests tests/category


4.3 Source file structure


/////////////////////////////////////////////////////////////////////
//
// project ......: LFC2
// file .........: fileName.cpp
// description ..: implementation of class File methods
//
/////////////////////////////////////////////////////////////////////
//
// notes:
// ......- source file notes here (optional)
//
/////////////////////////////////////////////////////////////////////

4.3.1 C++ headers

C++ header files should use the following technique (to avoid multiple inclusions of the same header):


#ifndef __LFC_INTERFACES_SCANABLE__
#define __LFC_INTERFACES_SCANABLE__
... the rest of the header ...
#endif // __LFC_INTERFACES_SCANABLE__

4.3.2 C++ sources

No specific observations.

4.3.3 C++ inline sources

No specific observations.

5 Comments

6 Indentation guides

7 Functions (methods)

Functions and methods will be formatted as follows:


Type foo(T1 arg1, T2 arg2, ...)
{
}
and
Type Class::foo (T1 arg1, T2 arg2, ...)
{
}

8 Classes

Classes will have the following general organization:

class ClassName : access Base
{
.... ... friends declaration ...

access:
.... ... member types ...

access:
.... ... constructors, destructors ...

access:
.... ... LFC signals ...

public:
.... ... public data members ...

public:
.... ... public methods ...

protected:
.... ... protected methods ...

private:
.... ... private methods ...

protected:
.... ... protected data ...

private:
.... ... private data ...

};

8.1 General class formatting guidelines

8.2 Class templates


template<class T1, class T2, ...>
class ClassName : access Base
{
};

8.3 Special class members

8.4 Multiple base classes and LFC ’interfaces’

In LFC, all classes, defined in the library or in an application using LFC, should inherit from Object class (directly of indirectly) and from zero or more ’interfaces’ (see LFC design doc about ’LFC interfaces’; you can recognize them because their name starts with an _ (underscore)).

When you inherit from a base class + one or more ’interfaces’ you should use this formatting:


class File :
....public Object,
....public virtual _Input<char>,
....public virtual _Output<char>,
....public virtual _Named
{
.......
};

9 C++ statements

9.1 If (if...else if...else)


if(expression)
....statement if(expression1)
....statement1
else if(expression2)
if(expression) ....statement2
....statement1 else
else ....statement3
....statement2


9.2 Switch


switch(expression)
{
case const1:
....... statements ...
case const2:
....... statements ...
default:
....... statements ...
}

9.3 While, do..while, for


while(expression)
....statement
do
....statement
while(expression);
do
{
....... statements ...
} while(expression);
for(exp1; exp2; exp3)
....statement

9.4 Try..catch


try
{
....... statements ...
}
catch(T1 e1)
{
}
catch(...)
{
}

9.5 Goto


{
....goto label;
.......
label:
....statement
.......
}

10 Declarations, expressions

11 Spacing