[docs] Reword some of the coding practices
Update with the new fixed point and units rules. Also, fix the grammar and clarify what to do with non-static private functions.
This commit is contained in:
parent
77579bbc5f
commit
d036d088aa
35
HACKING
35
HACKING
@ -5,6 +5,8 @@ General notes and rules on clutter core hacking;
|
|||||||
|
|
||||||
- Follow the CODING_STYLE document.
|
- Follow the CODING_STYLE document.
|
||||||
|
|
||||||
|
- Really, follow the CODING_STYLE document.
|
||||||
|
|
||||||
- All non static public API funcs should be documented in the source files
|
- All non static public API funcs should be documented in the source files
|
||||||
via gtk-doc. Structures, enumerations and macros should be documented in
|
via gtk-doc. Structures, enumerations and macros should be documented in
|
||||||
the header files.
|
the header files.
|
||||||
@ -13,14 +15,14 @@ General notes and rules on clutter core hacking;
|
|||||||
the eventual lifetime handling of the arguments/return values or locking
|
the eventual lifetime handling of the arguments/return values or locking
|
||||||
of mutexes.
|
of mutexes.
|
||||||
|
|
||||||
- All public functions with float parameters should also provide a fixed
|
- All public functions with floating point arguments should also provide a
|
||||||
point version, with the 'x' postfix to the function name, e.g.:
|
fixed point version, with the 'x' postfix to the function name, e.g.:
|
||||||
|
|
||||||
clutter_actor_set_foo - floating point
|
clutter_actor_set_foo - floating point
|
||||||
clutter_actor_set_foox - fixed point
|
clutter_actor_set_foox - fixed point
|
||||||
|
|
||||||
Fixed point should be always be used internally, except when precision
|
Fixed point might also be used internally if the 16.16 precision and
|
||||||
is paramount.
|
range allow it.
|
||||||
|
|
||||||
- All public functions dealing with pixels should also provide a
|
- All public functions dealing with pixels should also provide a
|
||||||
ClutterUnit version, with the 'u' postfix to the function name, e.g:
|
ClutterUnit version, with the 'u' postfix to the function name, e.g:
|
||||||
@ -31,13 +33,16 @@ General notes and rules on clutter core hacking;
|
|||||||
ClutterUnit should always be used internally.
|
ClutterUnit should always be used internally.
|
||||||
|
|
||||||
- Properties should always be in floating point (never fixed point).
|
- Properties should always be in floating point (never fixed point).
|
||||||
The preferred precision is double.
|
The preferred precision is double for angles, and single precision
|
||||||
|
for size and position -- especially if they have to be passed down
|
||||||
|
to COGL.
|
||||||
|
|
||||||
- Properties should use pixels whenever is possible. If sub-pixel
|
- Properties should use pixels whenever is possible. If sub-pixel
|
||||||
precision is fundamental, use ClutterParamSpecUnit and
|
precision is fundamental, use ClutterParamSpecUnit and
|
||||||
clutter_param_spec_unit() to install ClutterUnit properties, and
|
clutter_param_spec_unit() to install ClutterUnit properties, and
|
||||||
clutter_value_set_unit()/clutter_value_get_unit() to handle GValues in
|
clutter_value_set_unit()/clutter_value_get_unit() to handle GValues in
|
||||||
a safe way. Never install a ClutterUnit property using a GParamSpecInt.
|
a safe way. Never install a ClutterUnit property using a GParamSpecInt,
|
||||||
|
GParamSpecFloat or GParamSpecDouble.
|
||||||
|
|
||||||
- Public entry points must always check their arguments with
|
- Public entry points must always check their arguments with
|
||||||
g_return_if_fail() or g_return_val_if_fail().
|
g_return_if_fail() or g_return_val_if_fail().
|
||||||
@ -46,16 +51,22 @@ General notes and rules on clutter core hacking;
|
|||||||
do not use g_return_if_fail()/g_return_val_if_fail() as they might
|
do not use g_return_if_fail()/g_return_val_if_fail() as they might
|
||||||
be compiled out.
|
be compiled out.
|
||||||
|
|
||||||
- Really try to avoid if possible additions to clutter-private.h. Use
|
- If you need to share some state variable across source files use
|
||||||
accessor functions instead.
|
ClutterContext and a private accessor.
|
||||||
|
|
||||||
- Don't add direct GL calls but wrap with cogl (also adding GLES
|
- Private, non-static functions must begin with an underscore and
|
||||||
version if possible, or at least a stub).
|
be declared inside clutter-private.h.
|
||||||
|
|
||||||
- Use CLUTTER_NOTE() macro for debug statements.
|
- Don't add direct GL calls but add API to COGL (both GL and GL|ES
|
||||||
|
versions if possible).
|
||||||
|
|
||||||
|
- Use the CLUTTER_NOTE() macro for debug statements in Clutter, and
|
||||||
|
the COGL_NOTE() macro for debug statements in COGL. If necessary,
|
||||||
|
add a value inside ClutterDebugFlags or CoglDebugFlags to specify
|
||||||
|
the debug section.
|
||||||
|
|
||||||
- New features should also include an exhaustive test unit under
|
- New features should also include an exhaustive test unit under
|
||||||
tests/conform and, eventually, a user-interactive tes under
|
tests/conform and, eventually, a user-interactive test under
|
||||||
tests/interactive.
|
tests/interactive.
|
||||||
|
|
||||||
- When committing, use the standard git commit message format:
|
- When committing, use the standard git commit message format:
|
||||||
|
Loading…
x
Reference in New Issue
Block a user