Coding Conventions

General

Oyranos is written in C for portability. All types belonging to its API's are prefixed with a oy.
Oyranos objects naming is build after C++ conventions, where access to a class member is prefixed with the scope operator.
oyranos::oyClass::oyClassFunction
looks in Oyranos
oyClass_Function. Of course a function specific to a data object needs the object itself as argument, as the this pointer is not available.
Oyranos features a flexible memory management and allows easy integration with different memory management strategies.

Data Handling

Oyranos uses a mix of different structures. Among them are the basic C types, simple C structs and Oyranos managed structs. The structs are transparent for compile time typechecking and easy debugging at runtime.

Objects are transparent to allow easier debugging. But be aware to not change the private members of Oyranos objects directly. They are marked at end with a underscore _. Use the appropriate functions for each object instead. Otherwise the objects are in danger to be handled inadequately.

Memory Handling

Naming Conventions

Declaration types are distinguishable through the below described naming conventions.
A oy prefix is common for all functions, types and enums to display a namespace in C.
Functions words are starting upper case, (after the oy prefix) oyVersion()
Enums have all letters written upper case. Words are separated by underscore oyPROFILE_e
Variables are written lower case and words are separated by underscore. oy_domain_codeset
Macros are upper case and start with OY_ or oy: OY_HAVE_PNG
As one exception some macros are normal named to allow later typing: oyChar
Function alike macros are named like normal functions followed by a _m: oyColourOffset_m()
For enum alike macros it is more appropriate to omit the _M suffix: OY_TYPE_123A_8
Stucts words start upper case followed by a _s: oyProfile_s
Struct/object handling functions start upper case with the struct name, followed with the verb: oyProfile_GetChannelName()

Declaration Overview

Development Conventions

API Design

Oyranos API's handle various tasks. A important idea is to make colour management easy. Thus some API's are high level and only a few calls are needed to do the, hopefully, right thing. For finer control many low level API's are exposed.
It is as well possible to reimplement the Oyranos functionality. Some recommendations or standards are therefore provided at OpenICC. Feel free to contact the Oyranos project to discuss further details.
Internal API's handle low level file access, internal static lists and adapt to backends.

Object Design

Almost all Oyranos structs are based on the same structure oyStruct_s. They share first a member called type_ to better distinguish their type. The according value is available as a enum from oyOBJECT_e.
Each object should implement a appropriate oyStruct_Copy_f() and a oyStruct_Release_f() function member on position 2 and 3. These allow to easily cast to the same type of functions of other objects. Many object manipulators in Oyranos rely on this feature. Thus each object can implement list functionality with a common base in the above mentioned oyStructList_s. The resoning behind the above outlined use of a common struct base and API's is, even with C casting, these help in reducing code size, at easier maintaining and in fixing bugs.
The fourth member of a oyObject_s style struct is oy_ and features common properties, like memory management, naming and more.
A new simple Oyranos data data structure should contain the type_ specifier and the two members of type oyStruct_Copy_f() and oyStruct_Release_f(). Complex data structures should contain the type_ and oy_ structure to allow the advanced features. Otherwise the fourth member shall keep a intptr_t.
Providing of similiar functions for different Oyranos objects, allows their use in a abstract way. A soft typecheck is possible over the type_ member. For an example see the internal oyStructList_s struct with the according C API. As casting in C is always blind, it is better to avoid, except you know what you do.

API Naming

Keeping API members in a lexical relation allowes for later easy searching with tools of choice. So you find rather a getOyNamedColourName but oyNamedColour_GetName and can easily find the related functions in the appropriate NamedColour API. The sheme follows C++ syntax: (namespace)oy(ranos)::(class)NamedColour::(function)getName. This should as well help in designing OO wrappers to allow consistency among C Oyranos and its wrappers for various languages.

Generated on Tue Mar 10 09:46:20 2009 for Oyranos by  doxygen 1.5.8