Coding style

Latest revision as of 13:43, 4 November 2013

Bellow you can read about the coding style rules to preserve Yate's uniformity of the source code. You can find out about the files name conventions or comments style and a few tips for scripts written in PHP.
Yate's coding style (being enforced throughout the entire coding process) is clean and easy to understand. This will help you preserve the high standards of the code.
Yate is written in C++ and supports scripting in other programming languages like PHP who is described bellow.

[edit] C++ code

[edit] Files organization

The main parts of Yate are in directories:

• clients - files for Yate's Client interface.
• conf.d - the configuration files for Yate.
• docs - documentation of Yate's API.
• engine - the Engine classes.
• libs - the main libraries.
• modules:

• routing modules
• signaling modules
• script language bindings
• CDR modules

• share - here you can find scripts directory with important libraries that communicates with Yate, written in PHP and Python.
• tools - some useful bash scripts.
• windows - project files for Yate's functionality in Windows.

[edit] Files name conventions

This will keep the code clean and readable.

• Files names must have .cpp extension, include files must have .h
• All header files names must be lower case
• Module file name is always lower case
• Engine files names are mixed case just like class names meaning first letter is upper case and the others lower case

[edit] Comments

Add comments to make the source code easier to understand.

• Use exclusively C++ style comments in code definition
• Use C style comments in declarations only to provide documentation to kdoc or Doxygen
• Don't use comments to temporarily disable more than one line of code, use #if 0 ... #endif instead
• At the end of source code files please add settings for those that use vi or vim as editor: /* vi: set ts=8 sw=4 sts=4 noet: */

[edit] Indentation

Yate's code source is indentated with 4 positions per blocks using tabs of 8 positions at the beginning of each line.

[edit] Templates

• Avoid templates if at all possible, even those from standard template library (STL)

They will lead to increase compile times and memory usage, resulting in excessively large executables.

Almost all compilers produce confusing, unhelpful error messages when errors are detected in template code. This can make templates difficult to develop.

Many compilers have very poor support for templates, so the use of templates can make code less portable.

• Only use fully inline template classes and functions

Let's say that you have 2 classes with the same methods, the only difference are the types of objects with who they operate, then it's better to use inline templates classes. These concepts save program space and memory because the class is stored only in one place (usually in .h file) and is only executed when it is instantiated. Also it is easier to maintain.

By inlining your code where it is needed, your program will spend less time in the function call and return parts. It is supposed to make the code go faster, even as it goes larger. It is recommended to be used when functions are small.

Depending on what you want to accomplish and if it involves performance use them wisely.

[edit] Examples

You can write your own modules that can be included in the main branch of Yate or modules that are independent like this one: Datacard module for Yate. Datacard module is a datacard channel driver for Huawei UMTS modem.
This is a module who uses Yate, but is not in the main branch of Yate. It's an external module written in C++ for Yate and will compile as a separate project.
You can read more about external modules that are not in the main branch of Yate in How to compile an external module in C++ for Yate.

External modules can be written in other programming language like PHP, Python, Javascript.

Bellow you can find some information about coding style in PHP that is similar the one for C++ code.

[edit] PHP code

The style for writing external PHP modules and IVRs is very similar to the one for C++ code.
These modules can be started from Yate and communicate through pipes to the extmodule.
They can also be started from outside Yate and connect to a TCP or UNIX socket if a listener is configured in extmodule.

• Always require_once("libyate.php") towards the start of any module or library
• Never put anything outside the <?php ... ?> tags
• Properly declare static methods with the static keyword as required by PHP5 or higher
• The incoming message must be always acknowledged
• Use Yate::Output to send output to console or log file
• Use Yate::Debug to send debugging output to console or log file, this can be turned on or off by providing a boolean argument

See also

• Yate C++ API
• Writing an IVR