diff options
Diffstat (limited to 'modules/CIAO/docs/CIAO_Style_Guide.txt')
-rw-r--r-- | modules/CIAO/docs/CIAO_Style_Guide.txt | 60 |
1 files changed, 60 insertions, 0 deletions
diff --git a/modules/CIAO/docs/CIAO_Style_Guide.txt b/modules/CIAO/docs/CIAO_Style_Guide.txt new file mode 100644 index 00000000000..28c3245bc76 --- /dev/null +++ b/modules/CIAO/docs/CIAO_Style_Guide.txt @@ -0,0 +1,60 @@ +Error/Debug messages +======================== +ciao_debug_level () and associated environment are no longer used. +Instead, there are error message levels, in order from least to most +severe: + +LM_TRACE +LM_DEBUG +LM_INFO +LM_NOTICE +LM_WARNING +LM_ERROR +LM_CRITICAL +LM_ALERT +LM_EMERGENCY + +Please use the full range. Severity LM_TRACE through LM_NOTICE should +use ACE_DEBUG. LM_WARNING through LM_EMERGENCY should use ACE_ERROR. + +The verbosity of the logging output, i.e. which severity of logging +messages are output, is configured at runtime from the command line of +any CIAO executable with --log-level. + +Examples of usage: +LM_TRACE should be used for gratuitous tracing flow of execution +messages, and insignificant debug values. Feel free to be as detailed +as possible here, the purpose is to make our lives easier when users +are having problems. LM_DEBUG should be used to report significant +debugging values and configuration parameters. LM_INFO should be used +to report subactions (e.g. activiation of ports, establishment of +connections), and LM_NOTICE should be used to report significant +actions (e.g., component installation complete, container creation). + +Debug messages should begin with "ClassName::MethodName - ". +There is a macro in CIAO_common.h called CLINFO. This macro expands +to a set of default log message decorators, and should be prepended to +any and all debug messages and error messages, e.g.: + +ACE_DEBUG((LM_INFO, CLINFO + "Servant_Activator::etherialize - Your message here")); + +It is VERY IMPORTANT to follow this format for EVERY MESSAGE to make +it easier to filter and make sense of logging output. + +All methods (no exceptions!) must have a CIAO_TRACE statement at the +beginning. + +Memory Allocation +======================= +All calls to allocate memory should use ACE_NEW_THROW_EX with +CORBA::NO_MEMORY, e.g.: + +ACE_NEW_THROW_EX(pointer_var, constructor, CORBA::NO_MEMORY); + +Locking +======================= +Use gards as much as possible, using the _THROW_EX versions of the +acquisition macros throwing CORBA::NO_RESOURCES. + + |