You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@celix.apache.org by "pnoltes (via GitHub)" <gi...@apache.org> on 2023/05/06 09:37:39 UTC
[PR] Feature/coding conventions (celix)
pnoltes opened a new pull request, #544:
URL: https://github.com/apache/celix/pull/544
This PR introduces an Apache Celix Coding Convention document along with a .clang-format file.
These additions aim to streamline Celix development by promoting more readable and maintainable code.
Please consider this PR as a proposal and feel free to contribute suggestions for changes. However, if this PR is merged, compliance with the coding conventions and format style is encouraged during pull request reviews.
For this particular PR, I would appreciate receiving some more reviews to ensure that the proposed changes are widely accepted by the community.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "pnoltes (via GitHub)" <gi...@apache.org>.
pnoltes commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1195618879
##########
.clang-format:
##########
@@ -0,0 +1,27 @@
+BasedOnStyle: LLVM
+IndentWidth: 4
+AllowShortIfStatementsOnASingleLine: false
+AlwaysBreakTemplateDeclarations: Yes
+BinPackArguments: false
+BinPackParameters: false
+BreakBeforeBraces: Attach
+ColumnLimit: 120
+ConstructorInitializerIndentWidth: 4
+Cpp11BracedListStyle: true
+DerivePointerAlignment: false
+IncludeBlocks: Regroup
Review Comment:
I personally are not a fan of organizing headers manually, so I prefer adding a IncludeCategories section.
I have edited something, but this does not yet seem to work for me.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "pnoltes (via GitHub)" <gi...@apache.org>.
pnoltes commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1195618879
##########
.clang-format:
##########
@@ -0,0 +1,27 @@
+BasedOnStyle: LLVM
+IndentWidth: 4
+AllowShortIfStatementsOnASingleLine: false
+AlwaysBreakTemplateDeclarations: Yes
+BinPackArguments: false
+BinPackParameters: false
+BreakBeforeBraces: Attach
+ColumnLimit: 120
+ConstructorInitializerIndentWidth: 4
+Cpp11BracedListStyle: true
+DerivePointerAlignment: false
+IncludeBlocks: Regroup
Review Comment:
I personally are not a fan of organizing headers manually, so I prefer adding a IncludeCategories section.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "PengZheng (via GitHub)" <gi...@apache.org>.
PengZheng commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1188603128
##########
documents/development/README.md:
##########
@@ -0,0 +1,539 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
+- Add a `static constexpr const char * const VERSION` to the service class, for the service version.
+
+### C++ Bundles
+
+- Use `CamelCase` for C++ bundle target names.
+- Do _not_ use a `Celix` prefix for C++ bundle target names.
+- Use `celix::` prefixed aliases for C++ bundle targets.
+- Use `CamelCase` for C++ bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C++ bundle targets.
+- Use `Apache_Celix_` prefix for C++ bundle symbolic names.
+- Use `Apache Celix ` prefix for C++ bundle names.
+- Use a `celix_` prefix for C++ bundle filenames.
+- Use a group name starting with `celix/` for C++ bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(MyBundle
+ SOURCES src/MyBundle.cc
+ SYMBOLIC_NAME "Apache_Celix_MyBundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_MyBundle"
+ VERSION "1.0.0"
+ GROUP "celix/MyBundleGroup"
+)
+add_library(celix::MyBundle ALIAS MyBundle)
+```
+
+### Unit Tests Naming
+
+- The test fixture should have a`TestSuite` postfix.
+- The source file should be named after the test fixture name and use a `.cc` extension.
+- Testcase names should use `CamelCase` (starting with a capital) and have a `Test` postfix.
+- When using error injection (one of the `error_injector` libraries) a separate test suite should be used.
+ - A `ErrorInjectionTestSuite` postfix should be used for the test fixture.
+ - The error injection setup should be reset on the `TearDown` function or destructor of the test fixture.
+
+## Comments and Documentation
+
+- Use Doxygen for code documentation.
Review Comment:
Oops, I'm just against using Doxygen beyond documentation. Specifically it should not be used for comments. We'd better emphasize the difference between documentation and comments. I've encounter guys who just learn Doxygen use it for comments.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "rlenferink (via GitHub)" <gi...@apache.org>.
rlenferink commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1191555161
##########
documents/development/README.md:
##########
@@ -0,0 +1,537 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
Review Comment:
How about `&` / references? https://github.com/apache/celix/blob/fc18c65d66918b8223e85944b910f9c15776947b/bundles/shell/shell/api/celix/IShellCommand.h#L61
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "WopsS (via GitHub)" <gi...@apache.org>.
WopsS commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1192668869
##########
.clang-format:
##########
@@ -0,0 +1,27 @@
+BasedOnStyle: LLVM
+IndentWidth: 4
+AllowShortIfStatementsOnASingleLine: false
+AlwaysBreakTemplateDeclarations: Yes
+BinPackArguments: false
+BinPackParameters: false
+BreakBeforeBraces: Attach
+ColumnLimit: 120
+ConstructorInitializerIndentWidth: 4
+Cpp11BracedListStyle: true
+DerivePointerAlignment: false
+IncludeBlocks: Regroup
+KeepEmptyLinesAtTheStartOfBlocks: false
+NamespaceIndentation: None
+PointerAlignment: Right
+ReflowComments: true
+SortIncludes: false
+SpaceAfterCStyleCast: false
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeParens: ControlStatements
+SpaceInEmptyParentheses: false
+SpacesBeforeTrailingComments: 1
+SpacesInAngles: Never
+SpacesInCStyleCastParentheses: false
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+AlignEscapedNewlines: Right
Review Comment:
The following options are already set to the values here in clang-format 15:
- BreakBeforeBraces
- ConstructorInitializerIndentWidth
- Cpp11BracedListStyle
- NamespaceIndentation
- ReflowComments
- SpaceAfterCStyleCast
- SpaceBeforeAssignmentOperators
- SpaceBeforeParens
- SpaceInEmptyParentheses
- SpacesInAngles
- SpacesInCStyleCastParentheses
- SpacesInParentheses
- SpacesInSquareBrackets
- AlignEscapedNewlines
Should they be specified here? I find it redundant.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "pnoltes (via GitHub)" <gi...@apache.org>.
pnoltes commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1187710575
##########
documents/development/README.md:
##########
@@ -0,0 +1,539 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
Review Comment:
I think is is good to add some extra rules and examples for remote compatible service interfaces.
Indeed the future or RSA, polyglot and descriptor gen is more a future discussion.
Note that I did some - small - experimentation with libclang to parse remote service header and generate descriptors.
So I think this is feasible, but requires effort. And then maybe use something like python pycparser.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "WopsS (via GitHub)" <gi...@apache.org>.
WopsS commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1193966487
##########
.clang-format:
##########
@@ -0,0 +1,27 @@
+BasedOnStyle: LLVM
Review Comment:
I saw that the project is using few JavaScript files (not many), so I thought to be explicit here that these are intended to C/C++.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "pnoltes (via GitHub)" <gi...@apache.org>.
pnoltes commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1194936863
##########
documents/development/README.md:
##########
@@ -0,0 +1,537 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
Review Comment:
I prefer `impl` over `detail` for implementation details, because detail is more logical to be used broader than for implementation details .
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "WopsS (via GitHub)" <gi...@apache.org>.
WopsS commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1205840272
##########
.clang-format:
##########
@@ -0,0 +1,27 @@
+BasedOnStyle: LLVM
+IndentWidth: 4
+AllowShortIfStatementsOnASingleLine: false
+AlwaysBreakTemplateDeclarations: Yes
+BinPackArguments: false
+BinPackParameters: false
+BreakBeforeBraces: Attach
+ColumnLimit: 120
+ConstructorInitializerIndentWidth: 4
+Cpp11BracedListStyle: true
+DerivePointerAlignment: false
+IncludeBlocks: Regroup
Review Comment:
I've consistently encountered problemswith this setting while developing libraries, particularly when using angle brackets (`<>`) to include header files within the library. However, these problems don't seem to occur when using double quotes (`""`).
E.g.:
```cpp
// lib/detail/header1.cpp
#include <lib/detail/header1.hpp>
#include <lib/header2.hpp>
#include <lib/header3.hpp>
#include <memory>
#include <spdlog/spdlog.hpp>
```
will get reorganized in:
```cpp
// lib/detail/header1.cpp
#include <memory>
#include <lib/header2.hpp>
#include <lib/header3.hpp>
#include <lib/detail/header1.hpp> // This header should be at the top of the file in my opinion.
#include <spdlog/spdlog.hpp>
```
while, the following:
```cpp
// lib/detail/header1.cpp
#include "lib/detail/header1.hpp"
#include "lib/header2.hpp"
#include "lib/header3.hpp"
#include <memory>
#include <spdlog/spdlog.hpp>
```
will get reorganized in:
```cpp
// lib/detail/header1.cpp
#include "lib/detail/header1.hpp"
#include <memory>
#include "lib/header2.hpp"
#include "lib/header3.hpp"
#include <spdlog/spdlog.hpp>
```
##########
.clang-format:
##########
@@ -0,0 +1,27 @@
+BasedOnStyle: LLVM
+IndentWidth: 4
+AllowShortIfStatementsOnASingleLine: false
+AlwaysBreakTemplateDeclarations: Yes
+BinPackArguments: false
+BinPackParameters: false
+BreakBeforeBraces: Attach
+ColumnLimit: 120
+ConstructorInitializerIndentWidth: 4
+Cpp11BracedListStyle: true
+DerivePointerAlignment: false
+IncludeBlocks: Regroup
Review Comment:
I've consistently encountered problems with this setting while developing libraries, particularly when using angle brackets (`<>`) to include header files within the library. However, these problems don't seem to occur when using double quotes (`""`).
E.g.:
```cpp
// lib/detail/header1.cpp
#include <lib/detail/header1.hpp>
#include <lib/header2.hpp>
#include <lib/header3.hpp>
#include <memory>
#include <spdlog/spdlog.hpp>
```
will get reorganized in:
```cpp
// lib/detail/header1.cpp
#include <memory>
#include <lib/header2.hpp>
#include <lib/header3.hpp>
#include <lib/detail/header1.hpp> // This header should be at the top of the file in my opinion.
#include <spdlog/spdlog.hpp>
```
while, the following:
```cpp
// lib/detail/header1.cpp
#include "lib/detail/header1.hpp"
#include "lib/header2.hpp"
#include "lib/header3.hpp"
#include <memory>
#include <spdlog/spdlog.hpp>
```
will get reorganized in:
```cpp
// lib/detail/header1.cpp
#include "lib/detail/header1.hpp"
#include <memory>
#include "lib/header2.hpp"
#include "lib/header3.hpp"
#include <spdlog/spdlog.hpp>
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "WopsS (via GitHub)" <gi...@apache.org>.
WopsS commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1192634586
##########
documents/development/README.md:
##########
@@ -0,0 +1,537 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
Review Comment:
How deep can a namespace be? Can I do something like `celix::custom_implemntation_detail::some_other_namespace` or just a `celix::detail` is more than enough for an implementation specific class?
I think it is worth mentioning if you prefer the namespaces to be max 2 level deep, e.g. `celix::` and `celix::detail`. I think everything that is "implementation" specific and not part of the public API should be in `celix::detail` (max. 2 levels).
##########
documents/development/README.md:
##########
@@ -0,0 +1,537 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
Review Comment:
Is this convention referring to `get` and `set` prefixes?
##########
documents/development/README.md:
##########
@@ -0,0 +1,537 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
Review Comment:
Is there a preference for the base type of an enum? E.g.:
```cpp
enum class ServiceRegistrationState : std::int8_t
```
##########
documents/development/README.md:
##########
@@ -0,0 +1,537 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
Review Comment:
```suggestion
constexpr const char* const SERVICE_ID = "service.id";
```
##########
documents/development/README.md:
##########
@@ -0,0 +1,537 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
+- Add a `static constexpr const char * const VERSION` to the service class, for the service version.
+
+### C++ Bundles
+
+- Use `CamelCase` for C++ bundle target names.
+- Do _not_ use a `Celix` prefix for C++ bundle target names.
+- Use `celix::` prefixed aliases for C++ bundle targets.
+- Use `CamelCase` for C++ bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C++ bundle targets.
+- Use `Apache_Celix_` prefix for C++ bundle symbolic names.
+- Use `Apache Celix ` prefix for C++ bundle names.
+- Use a `celix_` prefix for C++ bundle filenames.
+- Use a group name starting with `celix/` for C++ bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(MyBundle
+ SOURCES src/MyBundle.cc
+ SYMBOLIC_NAME "Apache_Celix_MyBundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_MyBundle"
+ VERSION "1.0.0"
+ GROUP "celix/MyBundleGroup"
+)
+add_library(celix::MyBundle ALIAS MyBundle)
+```
+
+### Unit Tests Naming
+
+- The test fixture should have a`TestSuite` postfix.
+- The source file should be named after the test fixture name and use a `.cc` extension.
+- Testcase names should use `CamelCase` (starting with a capital) and have a `Test` postfix.
+- When using error injection (one of the `error_injector` libraries) a separate test suite should be used.
+ - A `ErrorInjectionTestSuite` postfix should be used for the test fixture.
+ - The error injection setup should be reset on the `TearDown` function or destructor of the test fixture.
+
+## Comments and Documentation
+
+- Use Doxygen for code documentation.
+- Write comments that explain the purpose of the code, focusing on the "why" rather than the "how".
+- Apply doxygen documentation to all public API's.
+- Use the javadoc style for doxygen documentation.
+- Use `@` instead of `\` for doxygen commands.
+- Start with a `@brief` command and a short description.
+- For `@param` commands also provide in, out, or in/out information.
+
+## Formatting and Indentation
+
+- Use spaces for indentation and use 4 spaces per indentation level.
+- Keep line lengths under 120 characters, if possible, to enhance readability.
+- Place opening braces on the same line as the control statement or function definition,
+ and closing braces on a new line aligned with the control statement or function definition.
+- Use a single space before and after operators and around assignment statements.
+- Add a space after control keywords (`if`, `for`, `while`, etc.) that are followed by a parenthesis.
+- Always use braces ({ }) for control structures, even for single-statement blocks, to prevent errors.
+- Add a space after control keywords (`else`, `do`, etc) that are followed by a brace.
+- Do not add a space after the function name and the opening parenthesis.
+- For new files apply clang-format using the project .clang-format file.
+ - Note that this can be done using a plugin for your IDE or by running `clang-format -i <file>`.
+
+## Control Structures
+
+- Use `if`, `else if`, and `else` statements to handle multiple conditions.
+- Use `switch` statements for multiple conditions with a default case.
+- Use `while` statements for loops that may not execute.
+- Use `do`/`while` statements for loops that must execute at least once.
+- Use `for` statements for loops with a known number of iterations.
+- The use of `goto` is not allowed, except for error handling.
Review Comment:
This is allowed in C++? I would suggest to not allow it, C++ has RAII for this (if I understood this correctly).
##########
documents/development/README.md:
##########
@@ -0,0 +1,537 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
+- Add a `static constexpr const char * const VERSION` to the service class, for the service version.
+
+### C++ Bundles
+
+- Use `CamelCase` for C++ bundle target names.
+- Do _not_ use a `Celix` prefix for C++ bundle target names.
+- Use `celix::` prefixed aliases for C++ bundle targets.
+- Use `CamelCase` for C++ bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C++ bundle targets.
+- Use `Apache_Celix_` prefix for C++ bundle symbolic names.
+- Use `Apache Celix ` prefix for C++ bundle names.
+- Use a `celix_` prefix for C++ bundle filenames.
+- Use a group name starting with `celix/` for C++ bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(MyBundle
+ SOURCES src/MyBundle.cc
+ SYMBOLIC_NAME "Apache_Celix_MyBundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_MyBundle"
+ VERSION "1.0.0"
+ GROUP "celix/MyBundleGroup"
+)
+add_library(celix::MyBundle ALIAS MyBundle)
+```
+
+### Unit Tests Naming
+
+- The test fixture should have a`TestSuite` postfix.
+- The source file should be named after the test fixture name and use a `.cc` extension.
+- Testcase names should use `CamelCase` (starting with a capital) and have a `Test` postfix.
+- When using error injection (one of the `error_injector` libraries) a separate test suite should be used.
+ - A `ErrorInjectionTestSuite` postfix should be used for the test fixture.
+ - The error injection setup should be reset on the `TearDown` function or destructor of the test fixture.
+
+## Comments and Documentation
+
+- Use Doxygen for code documentation.
+- Write comments that explain the purpose of the code, focusing on the "why" rather than the "how".
+- Apply doxygen documentation to all public API's.
+- Use the javadoc style for doxygen documentation.
+- Use `@` instead of `\` for doxygen commands.
+- Start with a `@brief` command and a short description.
+- For `@param` commands also provide in, out, or in/out information.
+
+## Formatting and Indentation
+
+- Use spaces for indentation and use 4 spaces per indentation level.
+- Keep line lengths under 120 characters, if possible, to enhance readability.
+- Place opening braces on the same line as the control statement or function definition,
+ and closing braces on a new line aligned with the control statement or function definition.
+- Use a single space before and after operators and around assignment statements.
+- Add a space after control keywords (`if`, `for`, `while`, etc.) that are followed by a parenthesis.
+- Always use braces ({ }) for control structures, even for single-statement blocks, to prevent errors.
+- Add a space after control keywords (`else`, `do`, etc) that are followed by a brace.
+- Do not add a space after the function name and the opening parenthesis.
+- For new files apply clang-format using the project .clang-format file.
+ - Note that this can be done using a plugin for your IDE or by running `clang-format -i <file>`.
+
+## Control Structures
+
+- Use `if`, `else if`, and `else` statements to handle multiple conditions.
+- Use `switch` statements for multiple conditions with a default case.
+- Use `while` statements for loops that may not execute.
+- Use `do`/`while` statements for loops that must execute at least once.
+- Use `for` statements for loops with a known number of iterations.
+- The use of `goto` is not allowed, except for error handling.
+- For C, try to prevent deeply nested control structures and prefer early returns or error handling `goto` statements.
+ - To prevent deeply nested control structures, the `CELIX_DO_IF` and `CELIX_GOTO_IF_ERR` macros can also be used.
+
+## Functions and Methods
+
+- Limit functions to a single responsibility or purpose, following the Single Responsibility Principle (SRP).
+- Keep functions short and focused, aiming for a length of fewer than 50 lines.
+- Ensure const correctness.
+- For C functions with a lot of different parameters, consider using an options struct.
+ - An options struct combined with a EMPTY_OPTIONS macro can be used to provide default values and a such
+ options struct can be updated backwards compatible.
+ - An options struct ensure that a lot of parameters can be configured, but also direct set on creation.
+- For C++ functions with a lot of different parameters, consider using a builder pattern.
+ - A builder pattern can be updated backwards compatible.
+ - A builder pattern ensure that a lot of parameters can be configured, but also direct set on construction.
+
+## Error Handling and Logging
+
+- For C++, throw an exception when an error occurs.
+- For C, if memory allocation is needed or another error can occur, ensure that a function returns a value
+ than can be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- Use consistent error handling techniques, such as returning error codes or using designated error handling functions.
+- Log errors, warnings, and other important events using the Apache Celix log helper functions or - for libraries -
+ the `celix_err` (TBD) functionality.
+- Always check for errors and log them.
+- Ensure error handling is correct, using test suite with error injection.
+
+## Error Injection
+
+- Use the Apache Celix error_injector libraries to inject errors in unit tests in a controlled way.
+- Create a separate test suite for error injection tests.
+- Reset error injection setup on the `TearDown` function or destructor of the test fixture.
+- If an - internal or external - function is missing error injection support, add it to the error_injector library.
+ - Try to create small error injector libraries for specific functionality.
+
+## Unit Test Approach
+
+- Use the Google Test framework for unit tests.
+- Use the Google Mock framework for mocking.
+- Use the Apache Celix error_injector libraries to inject errors in unit tests in a controlled way.
+- Test bundles by installing them in a programmatically created framework.
+- Test bundles by using their provided services and used services.
+- In most cases, libraries can be tested using a white box approach and bundles can be tested using a black box approach.
+- For libraries that are tested with the Apache Celix error_injector libraries or require access to private/hidden
+ functions, a separate "code under test" static library should be created.
+ This library should not hide its symbols and should have a `_cut` postfix.
+
+
+```cmake
+set(MY_LIB_SOURCES ...)
+set(MY_LIB_PUBLIC_LIBS ...)
+set(MY_LIB_PRIVATE_LIBS ...)
+add_library(my_lib SHARED ${MY_LIB_SOURCES})
+target_link_libraries(my_lib PUBLIC ${MY_LIB_PUBLIC_LIBS} PRIVATE ${MY_LIB_PRIVATE_LIBS})
+celix_target_hide_symbols(my_lib)
+...
+
+if (ENABLE_TESTING)
+ add_library(my_lib_cut STATIC ${MY_LIB_SOURCES})
+ target_link_libraries(my_lib_cut PUBLIC ${MY_LIB_PUBLIC_LIBS} ${MY_LIB_PRIVATE_LIBS})
+ target_include_directories(my_lib_cut PUBLIC
+ ${CMAKE_CURRENT_LIST_DIR}/src
+ ${CMAKE_CURRENT_LIST_DIR}/include
+ ${CMAKE_BINARY_DIR}/celix/gen/includes/my_lib
+ )
+endif ()
+```
+
+## Supported C and C++ Standards
+
+- C libraries should support C99. (TBD or C11))
+- C++ libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Unit test code can be written in C++17.
+
+## Library target properties
+
+For C and C++ shared libraries, the following target properties should be set:
+ - `VERSION` should be set to the library version.
+ - `SOVERSION` should be set to the library major version.
+ - `OUTPUT_NAME` should be set to the library name and should contain a `celix_` prefix.
+
+```cmake
+add_library(my_lib SHARED
+ src/my_lib.c)
+set_target_properties(my_lib
+ PROPERTIES
+ VERSION 1.0.0
+ SOVERSION 1
+ OUTPUT_NAME celix_my_lib)
+```
+
+For C and C++ static libraries, the following target properties should be set:
+ - `POSITION_INDEPENDENT_CODE` should be set to `ON` for static libraries.
+ - `OUTPUT_NAME` should be set to the library name and should contain a `celix_` prefix.
+
+```cmake
+add_library(my_lib STATIC
+ src/my_lib.c)
+set_target_properties(my_lib
+ PROPERTIES
+ POSITION_INDEPENDENT_CODE ON
+ OUTPUT_NAME celix_my_lib)
+```
+
+## Symbol Visibility
+
+- Header-only (INTERFACE) libraries should not configure symbol visibility.
+- Shared and static libraries should configure symbol visibility.
+ - Static library meant to be linked as PRIVATE should hide symbols.
+- Bundles should configure symbol visibility (this is done by default).
+
+### Configuring Symbol Visibility for C/C++ Libraries
+
+For Apache Celix shared libraries, symbol visibility should be configured using the CMake target
+properties `C_VISIBILITY_PRESET`, `CXX_VISIBILITY_PRESET` and `VISIBILITY_INLINES_HIDDEN` and a generated export
+header.
+
+The `C_VISIBILITY_PRESET` and `CXX_VISIBILITY_PRESET` target properties can be used to configure the default visibility
+of symbols in C and C++ code. The `VISIBILITY_INLINES_HIDDEN` property can be used to configure the visibility of
+inline functions. The `VISIBILITY_INLINES_HIDDEN` property is only supported for C++ code.
+
+The default visibility should be configured to hidden and symbols should be explicitly exported using the export
+marcos from a generated export header. The export header can be generated using the CMake function
+`generate_export_header`. Every library should have its own export header.
+
+For shared libraries, this can be done using the following CMake code:
+
+```cmake
+add_library(my_lib SHARED
+ src/my_lib.c)
+set_target_properties(my_lib PROPERTIES
+ C_VISIBILITY_PRESET hidden
+ #For C++ shared libraries also configure CXX_VISIBILITY_PRESET
+ CXX_VISIBILITY_PRESET hidden
+ VISIBILITY_INLINES_HIDDEN ON
+ OUTPUT_NAME celix_my_lib)
+target_include_directories(my_lib
+ PUBLIC
+ $<BUILD_INTERFACE:${CMAKE_BINARY_DIR}/celix/gen/includes/my_lib>
+ PRIVATE
+ src)
+
+#generate export header
+generate_export_header(my_lib
+ BASE_NAME "CELIX_MY_LIB"
+ EXPORT_FILE_NAME "${CMAKE_BINARY_DIR}/celix/gen/includes/my_lib/celix_my_lib_export.h")
+
+#install
+install(TARGETS my_lib EXPORT celix LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+ INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/celix_my_lib)
+install(DIRECTORY include/
+ DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/celix_my_lib)
+install(DIRECTORY ${CMAKE_BINARY_DIR}/celix/gen/includes/my_lib/
+ DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/celix_my_lib)
+```
+
+### Configuring Symbol Visibility for C/C++ Bundles
+
+For bundle, symbol visibility will default be configured to hidden. This can be default by providing
+the `DO_NOT_CONFIGURE_SYMBOL_VISIBILITY` option to the CMake `add_celix_bundle` function.
+
+If symbol visibility is not configured in the `add_celix_bundle`, symbol visibility should be configured the same
+way as a shared library.
+
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+## Branch naming
+
+- Prefix feature branches with `feature/`, hotfix branches with `hotfix/`, bugfix branches with `bugfix/`
+ and release branches with `release/`.
+- If you are working on an issue, prefix the branch name with the issue number. E.g., `feature/1234-add-feature`.
Review Comment:
```suggestion
- If you are working on an issue, prefix the branch name with the issue number and optionally add a short description of the branch. E.g., `feature/1234` or `feature/1234-add-feature`.
```
Or make it mandatory that it needs a short description.
##########
.clang-format:
##########
@@ -0,0 +1,27 @@
+BasedOnStyle: LLVM
+IndentWidth: 4
+AllowShortIfStatementsOnASingleLine: false
+AlwaysBreakTemplateDeclarations: Yes
+BinPackArguments: false
+BinPackParameters: false
+BreakBeforeBraces: Attach
+ColumnLimit: 120
+ConstructorInitializerIndentWidth: 4
+Cpp11BracedListStyle: true
+DerivePointerAlignment: false
+IncludeBlocks: Regroup
Review Comment:
I looked into clang-format 15 and it has the following for LLVM:
```
IncludeCategories:
- Regex: '^"(llvm|llvm-c|clang|clang-c)/'
Priority: 2
CaseSensitive: false
- Regex: '^(<|"(gtest|gmock|isl|json)/)'
Priority: 3
CaseSensitive: false
- Regex: '.*'
Priority: 1
CaseSensitive: false
```
which will result in STL headers being at the end of the include list, is this something that is preferred? I would recommend something like (based on LLVM configuration) this in a header or source file:
```
#include <HEADER_OF_CPP_IF_NEEDED>
#include <STL_HEADER_1>
#include <STL_HEADER_2>
#include <OTHER_LIB_HEADER_1>
#include <OTHER_LIB_HEADER_2>
#include <THIRD_PARTY_HEADERS>
```
I would even set this to `Preserved` and let the developer decide, or create a custom `IncludeCategories` block.
##########
.clang-format:
##########
@@ -0,0 +1,27 @@
+BasedOnStyle: LLVM
+IndentWidth: 4
+AllowShortIfStatementsOnASingleLine: false
+AlwaysBreakTemplateDeclarations: Yes
+BinPackArguments: false
+BinPackParameters: false
+BreakBeforeBraces: Attach
+ColumnLimit: 120
+ConstructorInitializerIndentWidth: 4
+Cpp11BracedListStyle: true
+DerivePointerAlignment: false
+IncludeBlocks: Regroup
+KeepEmptyLinesAtTheStartOfBlocks: false
+NamespaceIndentation: None
+PointerAlignment: Right
Review Comment:
```suggestion
PointerAlignment: Left
```
##########
documents/development/README.md:
##########
@@ -0,0 +1,537 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
+- Add a `static constexpr const char * const VERSION` to the service class, for the service version.
+
+### C++ Bundles
+
+- Use `CamelCase` for C++ bundle target names.
+- Do _not_ use a `Celix` prefix for C++ bundle target names.
+- Use `celix::` prefixed aliases for C++ bundle targets.
+- Use `CamelCase` for C++ bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C++ bundle targets.
+- Use `Apache_Celix_` prefix for C++ bundle symbolic names.
+- Use `Apache Celix ` prefix for C++ bundle names.
+- Use a `celix_` prefix for C++ bundle filenames.
+- Use a group name starting with `celix/` for C++ bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(MyBundle
+ SOURCES src/MyBundle.cc
+ SYMBOLIC_NAME "Apache_Celix_MyBundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_MyBundle"
+ VERSION "1.0.0"
+ GROUP "celix/MyBundleGroup"
+)
+add_library(celix::MyBundle ALIAS MyBundle)
+```
+
+### Unit Tests Naming
+
+- The test fixture should have a`TestSuite` postfix.
+- The source file should be named after the test fixture name and use a `.cc` extension.
+- Testcase names should use `CamelCase` (starting with a capital) and have a `Test` postfix.
+- When using error injection (one of the `error_injector` libraries) a separate test suite should be used.
+ - A `ErrorInjectionTestSuite` postfix should be used for the test fixture.
+ - The error injection setup should be reset on the `TearDown` function or destructor of the test fixture.
+
+## Comments and Documentation
+
+- Use Doxygen for code documentation.
+- Write comments that explain the purpose of the code, focusing on the "why" rather than the "how".
+- Apply doxygen documentation to all public API's.
+- Use the javadoc style for doxygen documentation.
+- Use `@` instead of `\` for doxygen commands.
+- Start with a `@brief` command and a short description.
+- For `@param` commands also provide in, out, or in/out information.
+
+## Formatting and Indentation
+
+- Use spaces for indentation and use 4 spaces per indentation level.
+- Keep line lengths under 120 characters, if possible, to enhance readability.
+- Place opening braces on the same line as the control statement or function definition,
+ and closing braces on a new line aligned with the control statement or function definition.
+- Use a single space before and after operators and around assignment statements.
+- Add a space after control keywords (`if`, `for`, `while`, etc.) that are followed by a parenthesis.
+- Always use braces ({ }) for control structures, even for single-statement blocks, to prevent errors.
+- Add a space after control keywords (`else`, `do`, etc) that are followed by a brace.
+- Do not add a space after the function name and the opening parenthesis.
+- For new files apply clang-format using the project .clang-format file.
+ - Note that this can be done using a plugin for your IDE or by running `clang-format -i <file>`.
+
+## Control Structures
+
+- Use `if`, `else if`, and `else` statements to handle multiple conditions.
+- Use `switch` statements for multiple conditions with a default case.
+- Use `while` statements for loops that may not execute.
+- Use `do`/`while` statements for loops that must execute at least once.
+- Use `for` statements for loops with a known number of iterations.
+- The use of `goto` is not allowed, except for error handling.
+- For C, try to prevent deeply nested control structures and prefer early returns or error handling `goto` statements.
+ - To prevent deeply nested control structures, the `CELIX_DO_IF` and `CELIX_GOTO_IF_ERR` macros can also be used.
+
+## Functions and Methods
+
+- Limit functions to a single responsibility or purpose, following the Single Responsibility Principle (SRP).
+- Keep functions short and focused, aiming for a length of fewer than 50 lines.
+- Ensure const correctness.
+- For C functions with a lot of different parameters, consider using an options struct.
+ - An options struct combined with a EMPTY_OPTIONS macro can be used to provide default values and a such
+ options struct can be updated backwards compatible.
+ - An options struct ensure that a lot of parameters can be configured, but also direct set on creation.
+- For C++ functions with a lot of different parameters, consider using a builder pattern.
+ - A builder pattern can be updated backwards compatible.
Review Comment:
I find it a bit strange this sentence, did you mean:
```suggestion
- A builder pattern can be updated to be backwards compatible.
```
or
```suggestion
- A builder pattern can be backwards compatible.
```
##########
documents/development/README.md:
##########
@@ -0,0 +1,537 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
+- Add a `static constexpr const char * const VERSION` to the service class, for the service version.
+
+### C++ Bundles
+
+- Use `CamelCase` for C++ bundle target names.
+- Do _not_ use a `Celix` prefix for C++ bundle target names.
+- Use `celix::` prefixed aliases for C++ bundle targets.
+- Use `CamelCase` for C++ bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C++ bundle targets.
+- Use `Apache_Celix_` prefix for C++ bundle symbolic names.
+- Use `Apache Celix ` prefix for C++ bundle names.
+- Use a `celix_` prefix for C++ bundle filenames.
+- Use a group name starting with `celix/` for C++ bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(MyBundle
+ SOURCES src/MyBundle.cc
+ SYMBOLIC_NAME "Apache_Celix_MyBundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_MyBundle"
+ VERSION "1.0.0"
+ GROUP "celix/MyBundleGroup"
+)
+add_library(celix::MyBundle ALIAS MyBundle)
+```
+
+### Unit Tests Naming
+
+- The test fixture should have a`TestSuite` postfix.
+- The source file should be named after the test fixture name and use a `.cc` extension.
+- Testcase names should use `CamelCase` (starting with a capital) and have a `Test` postfix.
+- When using error injection (one of the `error_injector` libraries) a separate test suite should be used.
+ - A `ErrorInjectionTestSuite` postfix should be used for the test fixture.
+ - The error injection setup should be reset on the `TearDown` function or destructor of the test fixture.
+
+## Comments and Documentation
+
+- Use Doxygen for code documentation.
+- Write comments that explain the purpose of the code, focusing on the "why" rather than the "how".
+- Apply doxygen documentation to all public API's.
+- Use the javadoc style for doxygen documentation.
+- Use `@` instead of `\` for doxygen commands.
+- Start with a `@brief` command and a short description.
+- For `@param` commands also provide in, out, or in/out information.
+
+## Formatting and Indentation
+
+- Use spaces for indentation and use 4 spaces per indentation level.
+- Keep line lengths under 120 characters, if possible, to enhance readability.
+- Place opening braces on the same line as the control statement or function definition,
+ and closing braces on a new line aligned with the control statement or function definition.
+- Use a single space before and after operators and around assignment statements.
+- Add a space after control keywords (`if`, `for`, `while`, etc.) that are followed by a parenthesis.
+- Always use braces ({ }) for control structures, even for single-statement blocks, to prevent errors.
+- Add a space after control keywords (`else`, `do`, etc) that are followed by a brace.
+- Do not add a space after the function name and the opening parenthesis.
+- For new files apply clang-format using the project .clang-format file.
+ - Note that this can be done using a plugin for your IDE or by running `clang-format -i <file>`.
+
+## Control Structures
+
+- Use `if`, `else if`, and `else` statements to handle multiple conditions.
+- Use `switch` statements for multiple conditions with a default case.
+- Use `while` statements for loops that may not execute.
+- Use `do`/`while` statements for loops that must execute at least once.
+- Use `for` statements for loops with a known number of iterations.
+- The use of `goto` is not allowed, except for error handling.
+- For C, try to prevent deeply nested control structures and prefer early returns or error handling `goto` statements.
+ - To prevent deeply nested control structures, the `CELIX_DO_IF` and `CELIX_GOTO_IF_ERR` macros can also be used.
+
+## Functions and Methods
+
+- Limit functions to a single responsibility or purpose, following the Single Responsibility Principle (SRP).
+- Keep functions short and focused, aiming for a length of fewer than 50 lines.
+- Ensure const correctness.
+- For C functions with a lot of different parameters, consider using an options struct.
+ - An options struct combined with a EMPTY_OPTIONS macro can be used to provide default values and a such
+ options struct can be updated backwards compatible.
+ - An options struct ensure that a lot of parameters can be configured, but also direct set on creation.
+- For C++ functions with a lot of different parameters, consider using a builder pattern.
+ - A builder pattern can be updated backwards compatible.
+ - A builder pattern ensure that a lot of parameters can be configured, but also direct set on construction.
+
+## Error Handling and Logging
+
+- For C++, throw an exception when an error occurs.
+- For C, if memory allocation is needed or another error can occur, ensure that a function returns a value
+ than can be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- Use consistent error handling techniques, such as returning error codes or using designated error handling functions.
+- Log errors, warnings, and other important events using the Apache Celix log helper functions or - for libraries -
+ the `celix_err` (TBD) functionality.
+- Always check for errors and log them.
+- Ensure error handling is correct, using test suite with error injection.
+
+## Error Injection
+
+- Use the Apache Celix error_injector libraries to inject errors in unit tests in a controlled way.
+- Create a separate test suite for error injection tests.
+- Reset error injection setup on the `TearDown` function or destructor of the test fixture.
+- If an - internal or external - function is missing error injection support, add it to the error_injector library.
+ - Try to create small error injector libraries for specific functionality.
+
+## Unit Test Approach
+
+- Use the Google Test framework for unit tests.
+- Use the Google Mock framework for mocking.
+- Use the Apache Celix error_injector libraries to inject errors in unit tests in a controlled way.
+- Test bundles by installing them in a programmatically created framework.
+- Test bundles by using their provided services and used services.
+- In most cases, libraries can be tested using a white box approach and bundles can be tested using a black box approach.
+- For libraries that are tested with the Apache Celix error_injector libraries or require access to private/hidden
+ functions, a separate "code under test" static library should be created.
+ This library should not hide its symbols and should have a `_cut` postfix.
+
+
+```cmake
+set(MY_LIB_SOURCES ...)
+set(MY_LIB_PUBLIC_LIBS ...)
+set(MY_LIB_PRIVATE_LIBS ...)
+add_library(my_lib SHARED ${MY_LIB_SOURCES})
+target_link_libraries(my_lib PUBLIC ${MY_LIB_PUBLIC_LIBS} PRIVATE ${MY_LIB_PRIVATE_LIBS})
+celix_target_hide_symbols(my_lib)
+...
+
+if (ENABLE_TESTING)
+ add_library(my_lib_cut STATIC ${MY_LIB_SOURCES})
+ target_link_libraries(my_lib_cut PUBLIC ${MY_LIB_PUBLIC_LIBS} ${MY_LIB_PRIVATE_LIBS})
+ target_include_directories(my_lib_cut PUBLIC
+ ${CMAKE_CURRENT_LIST_DIR}/src
+ ${CMAKE_CURRENT_LIST_DIR}/include
+ ${CMAKE_BINARY_DIR}/celix/gen/includes/my_lib
+ )
+endif ()
+```
+
+## Supported C and C++ Standards
+
+- C libraries should support C99. (TBD or C11))
+- C++ libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Unit test code can be written in C++17.
+
+## Library target properties
+
+For C and C++ shared libraries, the following target properties should be set:
+ - `VERSION` should be set to the library version.
+ - `SOVERSION` should be set to the library major version.
+ - `OUTPUT_NAME` should be set to the library name and should contain a `celix_` prefix.
+
+```cmake
+add_library(my_lib SHARED
+ src/my_lib.c)
+set_target_properties(my_lib
+ PROPERTIES
+ VERSION 1.0.0
+ SOVERSION 1
+ OUTPUT_NAME celix_my_lib)
+```
+
+For C and C++ static libraries, the following target properties should be set:
+ - `POSITION_INDEPENDENT_CODE` should be set to `ON` for static libraries.
+ - `OUTPUT_NAME` should be set to the library name and should contain a `celix_` prefix.
+
+```cmake
+add_library(my_lib STATIC
+ src/my_lib.c)
+set_target_properties(my_lib
+ PROPERTIES
+ POSITION_INDEPENDENT_CODE ON
+ OUTPUT_NAME celix_my_lib)
+```
+
+## Symbol Visibility
+
+- Header-only (INTERFACE) libraries should not configure symbol visibility.
+- Shared and static libraries should configure symbol visibility.
+ - Static library meant to be linked as PRIVATE should hide symbols.
+- Bundles should configure symbol visibility (this is done by default).
+
+### Configuring Symbol Visibility for C/C++ Libraries
+
+For Apache Celix shared libraries, symbol visibility should be configured using the CMake target
+properties `C_VISIBILITY_PRESET`, `CXX_VISIBILITY_PRESET` and `VISIBILITY_INLINES_HIDDEN` and a generated export
+header.
+
+The `C_VISIBILITY_PRESET` and `CXX_VISIBILITY_PRESET` target properties can be used to configure the default visibility
+of symbols in C and C++ code. The `VISIBILITY_INLINES_HIDDEN` property can be used to configure the visibility of
+inline functions. The `VISIBILITY_INLINES_HIDDEN` property is only supported for C++ code.
+
+The default visibility should be configured to hidden and symbols should be explicitly exported using the export
+marcos from a generated export header. The export header can be generated using the CMake function
+`generate_export_header`. Every library should have its own export header.
+
+For shared libraries, this can be done using the following CMake code:
+
+```cmake
+add_library(my_lib SHARED
+ src/my_lib.c)
+set_target_properties(my_lib PROPERTIES
+ C_VISIBILITY_PRESET hidden
+ #For C++ shared libraries also configure CXX_VISIBILITY_PRESET
+ CXX_VISIBILITY_PRESET hidden
+ VISIBILITY_INLINES_HIDDEN ON
+ OUTPUT_NAME celix_my_lib)
+target_include_directories(my_lib
+ PUBLIC
+ $<BUILD_INTERFACE:${CMAKE_BINARY_DIR}/celix/gen/includes/my_lib>
+ PRIVATE
+ src)
+
+#generate export header
+generate_export_header(my_lib
+ BASE_NAME "CELIX_MY_LIB"
+ EXPORT_FILE_NAME "${CMAKE_BINARY_DIR}/celix/gen/includes/my_lib/celix_my_lib_export.h")
+
+#install
+install(TARGETS my_lib EXPORT celix LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+ INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/celix_my_lib)
+install(DIRECTORY include/
+ DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/celix_my_lib)
+install(DIRECTORY ${CMAKE_BINARY_DIR}/celix/gen/includes/my_lib/
+ DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/celix_my_lib)
+```
+
+### Configuring Symbol Visibility for C/C++ Bundles
+
+For bundle, symbol visibility will default be configured to hidden. This can be default by providing
+the `DO_NOT_CONFIGURE_SYMBOL_VISIBILITY` option to the CMake `add_celix_bundle` function.
+
+If symbol visibility is not configured in the `add_celix_bundle`, symbol visibility should be configured the same
+way as a shared library.
+
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+## Branch naming
+
+- Prefix feature branches with `feature/`, hotfix branches with `hotfix/`, bugfix branches with `bugfix/`
+ and release branches with `release/`.
+- If you are working on an issue, prefix the branch name with the issue number. E.g., `feature/1234-add-feature`.
+- Hotfix branches are for urgent fixes that need to be applied as soon as possible.
+- Use short and descriptive branch names.
Review Comment:
I would put this first.
##########
.clang-format:
##########
@@ -0,0 +1,27 @@
+BasedOnStyle: LLVM
+IndentWidth: 4
+AllowShortIfStatementsOnASingleLine: false
+AlwaysBreakTemplateDeclarations: Yes
+BinPackArguments: false
+BinPackParameters: false
+BreakBeforeBraces: Attach
+ColumnLimit: 120
+ConstructorInitializerIndentWidth: 4
+Cpp11BracedListStyle: true
+DerivePointerAlignment: false
+IncludeBlocks: Regroup
+KeepEmptyLinesAtTheStartOfBlocks: false
+NamespaceIndentation: None
+PointerAlignment: Right
+ReflowComments: true
+SortIncludes: false
Review Comment:
Is there a reason for disabling this option? I think it is a good one to be enabled.
##########
.clang-format:
##########
@@ -0,0 +1,27 @@
+BasedOnStyle: LLVM
Review Comment:
Since this can be done for other languages, I suggest:
```suggestion
---
BasedOnStyle: LLVM
---
Language: Cpp
```
##########
.clang-format:
##########
@@ -0,0 +1,27 @@
+BasedOnStyle: LLVM
+IndentWidth: 4
+AllowShortIfStatementsOnASingleLine: false
+AlwaysBreakTemplateDeclarations: Yes
+BinPackArguments: false
+BinPackParameters: false
+BreakBeforeBraces: Attach
+ColumnLimit: 120
+ConstructorInitializerIndentWidth: 4
+Cpp11BracedListStyle: true
+DerivePointerAlignment: false
+IncludeBlocks: Regroup
+KeepEmptyLinesAtTheStartOfBlocks: false
+NamespaceIndentation: None
+PointerAlignment: Right
+ReflowComments: true
+SortIncludes: false
+SpaceAfterCStyleCast: false
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeParens: ControlStatements
+SpaceInEmptyParentheses: false
+SpacesBeforeTrailingComments: 1
+SpacesInAngles: Never
+SpacesInCStyleCastParentheses: false
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+AlignEscapedNewlines: Right
Review Comment:
The following options are already set to the values here in clang-format 15:
- BreakBeforeBraces
- ConstructorInitializerIndentWidth
- Cpp11BracedListStyle
- NamespaceIndentation
- ReflowComments
- SpaceAfterCStyleCast
- SpaceBeforeAssignmentOperators
- SpaceBeforeParens
- SpaceInEmptyParentheses
- SpacesInAngles
- SpacesInCStyleCastParentheses
- SpacesInParentheses
- SpacesInSquareBrackets
- AlignEscapedNewlines
Should they be specified here? I find it redundant.
##########
documents/development/README.md:
##########
@@ -0,0 +1,537 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
+- Add a `static constexpr const char * const VERSION` to the service class, for the service version.
+
+### C++ Bundles
+
+- Use `CamelCase` for C++ bundle target names.
+- Do _not_ use a `Celix` prefix for C++ bundle target names.
+- Use `celix::` prefixed aliases for C++ bundle targets.
+- Use `CamelCase` for C++ bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C++ bundle targets.
+- Use `Apache_Celix_` prefix for C++ bundle symbolic names.
+- Use `Apache Celix ` prefix for C++ bundle names.
+- Use a `celix_` prefix for C++ bundle filenames.
+- Use a group name starting with `celix/` for C++ bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(MyBundle
+ SOURCES src/MyBundle.cc
+ SYMBOLIC_NAME "Apache_Celix_MyBundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_MyBundle"
+ VERSION "1.0.0"
+ GROUP "celix/MyBundleGroup"
+)
+add_library(celix::MyBundle ALIAS MyBundle)
+```
+
+### Unit Tests Naming
+
+- The test fixture should have a`TestSuite` postfix.
+- The source file should be named after the test fixture name and use a `.cc` extension.
+- Testcase names should use `CamelCase` (starting with a capital) and have a `Test` postfix.
+- When using error injection (one of the `error_injector` libraries) a separate test suite should be used.
+ - A `ErrorInjectionTestSuite` postfix should be used for the test fixture.
+ - The error injection setup should be reset on the `TearDown` function or destructor of the test fixture.
+
+## Comments and Documentation
+
+- Use Doxygen for code documentation.
+- Write comments that explain the purpose of the code, focusing on the "why" rather than the "how".
+- Apply doxygen documentation to all public API's.
+- Use the javadoc style for doxygen documentation.
+- Use `@` instead of `\` for doxygen commands.
+- Start with a `@brief` command and a short description.
+- For `@param` commands also provide in, out, or in/out information.
+
+## Formatting and Indentation
+
+- Use spaces for indentation and use 4 spaces per indentation level.
+- Keep line lengths under 120 characters, if possible, to enhance readability.
+- Place opening braces on the same line as the control statement or function definition,
+ and closing braces on a new line aligned with the control statement or function definition.
+- Use a single space before and after operators and around assignment statements.
+- Add a space after control keywords (`if`, `for`, `while`, etc.) that are followed by a parenthesis.
+- Always use braces ({ }) for control structures, even for single-statement blocks, to prevent errors.
+- Add a space after control keywords (`else`, `do`, etc) that are followed by a brace.
+- Do not add a space after the function name and the opening parenthesis.
+- For new files apply clang-format using the project .clang-format file.
+ - Note that this can be done using a plugin for your IDE or by running `clang-format -i <file>`.
+
+## Control Structures
+
+- Use `if`, `else if`, and `else` statements to handle multiple conditions.
+- Use `switch` statements for multiple conditions with a default case.
+- Use `while` statements for loops that may not execute.
+- Use `do`/`while` statements for loops that must execute at least once.
+- Use `for` statements for loops with a known number of iterations.
+- The use of `goto` is not allowed, except for error handling.
+- For C, try to prevent deeply nested control structures and prefer early returns or error handling `goto` statements.
+ - To prevent deeply nested control structures, the `CELIX_DO_IF` and `CELIX_GOTO_IF_ERR` macros can also be used.
+
+## Functions and Methods
+
+- Limit functions to a single responsibility or purpose, following the Single Responsibility Principle (SRP).
+- Keep functions short and focused, aiming for a length of fewer than 50 lines.
+- Ensure const correctness.
Review Comment:
I would link this to https://isocpp.org/wiki/faq/const-correctness, it is a nice page for it.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "pnoltes (via GitHub)" <gi...@apache.org>.
pnoltes commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1194932607
##########
documents/development/README.md:
##########
@@ -0,0 +1,537 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
+- Add a `static constexpr const char * const VERSION` to the service class, for the service version.
+
+### C++ Bundles
+
+- Use `CamelCase` for C++ bundle target names.
+- Do _not_ use a `Celix` prefix for C++ bundle target names.
+- Use `celix::` prefixed aliases for C++ bundle targets.
+- Use `CamelCase` for C++ bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C++ bundle targets.
+- Use `Apache_Celix_` prefix for C++ bundle symbolic names.
+- Use `Apache Celix ` prefix for C++ bundle names.
+- Use a `celix_` prefix for C++ bundle filenames.
+- Use a group name starting with `celix/` for C++ bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(MyBundle
+ SOURCES src/MyBundle.cc
+ SYMBOLIC_NAME "Apache_Celix_MyBundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_MyBundle"
+ VERSION "1.0.0"
+ GROUP "celix/MyBundleGroup"
+)
+add_library(celix::MyBundle ALIAS MyBundle)
+```
+
+### Unit Tests Naming
+
+- The test fixture should have a`TestSuite` postfix.
+- The source file should be named after the test fixture name and use a `.cc` extension.
+- Testcase names should use `CamelCase` (starting with a capital) and have a `Test` postfix.
+- When using error injection (one of the `error_injector` libraries) a separate test suite should be used.
+ - A `ErrorInjectionTestSuite` postfix should be used for the test fixture.
+ - The error injection setup should be reset on the `TearDown` function or destructor of the test fixture.
+
+## Comments and Documentation
+
+- Use Doxygen for code documentation.
+- Write comments that explain the purpose of the code, focusing on the "why" rather than the "how".
+- Apply doxygen documentation to all public API's.
+- Use the javadoc style for doxygen documentation.
+- Use `@` instead of `\` for doxygen commands.
+- Start with a `@brief` command and a short description.
+- For `@param` commands also provide in, out, or in/out information.
+
+## Formatting and Indentation
+
+- Use spaces for indentation and use 4 spaces per indentation level.
+- Keep line lengths under 120 characters, if possible, to enhance readability.
+- Place opening braces on the same line as the control statement or function definition,
+ and closing braces on a new line aligned with the control statement or function definition.
+- Use a single space before and after operators and around assignment statements.
+- Add a space after control keywords (`if`, `for`, `while`, etc.) that are followed by a parenthesis.
+- Always use braces ({ }) for control structures, even for single-statement blocks, to prevent errors.
+- Add a space after control keywords (`else`, `do`, etc) that are followed by a brace.
+- Do not add a space after the function name and the opening parenthesis.
+- For new files apply clang-format using the project .clang-format file.
+ - Note that this can be done using a plugin for your IDE or by running `clang-format -i <file>`.
+
+## Control Structures
+
+- Use `if`, `else if`, and `else` statements to handle multiple conditions.
+- Use `switch` statements for multiple conditions with a default case.
+- Use `while` statements for loops that may not execute.
+- Use `do`/`while` statements for loops that must execute at least once.
+- Use `for` statements for loops with a known number of iterations.
+- The use of `goto` is not allowed, except for error handling.
+- For C, try to prevent deeply nested control structures and prefer early returns or error handling `goto` statements.
+ - To prevent deeply nested control structures, the `CELIX_DO_IF` and `CELIX_GOTO_IF_ERR` macros can also be used.
+
+## Functions and Methods
+
+- Limit functions to a single responsibility or purpose, following the Single Responsibility Principle (SRP).
+- Keep functions short and focused, aiming for a length of fewer than 50 lines.
+- Ensure const correctness.
+- For C functions with a lot of different parameters, consider using an options struct.
+ - An options struct combined with a EMPTY_OPTIONS macro can be used to provide default values and a such
+ options struct can be updated backwards compatible.
+ - An options struct ensure that a lot of parameters can be configured, but also direct set on creation.
+- For C++ functions with a lot of different parameters, consider using a builder pattern.
+ - A builder pattern can be updated backwards compatible.
+ - A builder pattern ensure that a lot of parameters can be configured, but also direct set on construction.
+
+## Error Handling and Logging
+
+- For C++, throw an exception when an error occurs.
+- For C, if memory allocation is needed or another error can occur, ensure that a function returns a value
+ than can be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- Use consistent error handling techniques, such as returning error codes or using designated error handling functions.
+- Log errors, warnings, and other important events using the Apache Celix log helper functions or - for libraries -
+ the `celix_err` (TBD) functionality.
+- Always check for errors and log them.
+- Ensure error handling is correct, using test suite with error injection.
+
+## Error Injection
+
+- Use the Apache Celix error_injector libraries to inject errors in unit tests in a controlled way.
+- Create a separate test suite for error injection tests.
+- Reset error injection setup on the `TearDown` function or destructor of the test fixture.
+- If an - internal or external - function is missing error injection support, add it to the error_injector library.
+ - Try to create small error injector libraries for specific functionality.
+
+## Unit Test Approach
+
+- Use the Google Test framework for unit tests.
+- Use the Google Mock framework for mocking.
+- Use the Apache Celix error_injector libraries to inject errors in unit tests in a controlled way.
+- Test bundles by installing them in a programmatically created framework.
+- Test bundles by using their provided services and used services.
+- In most cases, libraries can be tested using a white box approach and bundles can be tested using a black box approach.
+- For libraries that are tested with the Apache Celix error_injector libraries or require access to private/hidden
+ functions, a separate "code under test" static library should be created.
+ This library should not hide its symbols and should have a `_cut` postfix.
+
+
+```cmake
+set(MY_LIB_SOURCES ...)
+set(MY_LIB_PUBLIC_LIBS ...)
+set(MY_LIB_PRIVATE_LIBS ...)
+add_library(my_lib SHARED ${MY_LIB_SOURCES})
+target_link_libraries(my_lib PUBLIC ${MY_LIB_PUBLIC_LIBS} PRIVATE ${MY_LIB_PRIVATE_LIBS})
+celix_target_hide_symbols(my_lib)
+...
+
+if (ENABLE_TESTING)
+ add_library(my_lib_cut STATIC ${MY_LIB_SOURCES})
+ target_link_libraries(my_lib_cut PUBLIC ${MY_LIB_PUBLIC_LIBS} ${MY_LIB_PRIVATE_LIBS})
+ target_include_directories(my_lib_cut PUBLIC
+ ${CMAKE_CURRENT_LIST_DIR}/src
+ ${CMAKE_CURRENT_LIST_DIR}/include
+ ${CMAKE_BINARY_DIR}/celix/gen/includes/my_lib
+ )
+endif ()
+```
+
+## Supported C and C++ Standards
+
+- C libraries should support C99. (TBD or C11))
+- C++ libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Unit test code can be written in C++17.
+
+## Library target properties
+
+For C and C++ shared libraries, the following target properties should be set:
+ - `VERSION` should be set to the library version.
+ - `SOVERSION` should be set to the library major version.
+ - `OUTPUT_NAME` should be set to the library name and should contain a `celix_` prefix.
+
+```cmake
+add_library(my_lib SHARED
+ src/my_lib.c)
+set_target_properties(my_lib
+ PROPERTIES
+ VERSION 1.0.0
+ SOVERSION 1
+ OUTPUT_NAME celix_my_lib)
+```
+
+For C and C++ static libraries, the following target properties should be set:
+ - `POSITION_INDEPENDENT_CODE` should be set to `ON` for static libraries.
+ - `OUTPUT_NAME` should be set to the library name and should contain a `celix_` prefix.
+
+```cmake
+add_library(my_lib STATIC
+ src/my_lib.c)
+set_target_properties(my_lib
+ PROPERTIES
+ POSITION_INDEPENDENT_CODE ON
+ OUTPUT_NAME celix_my_lib)
+```
+
+## Symbol Visibility
+
+- Header-only (INTERFACE) libraries should not configure symbol visibility.
+- Shared and static libraries should configure symbol visibility.
+ - Static library meant to be linked as PRIVATE should hide symbols.
+- Bundles should configure symbol visibility (this is done by default).
+
+### Configuring Symbol Visibility for C/C++ Libraries
+
+For Apache Celix shared libraries, symbol visibility should be configured using the CMake target
+properties `C_VISIBILITY_PRESET`, `CXX_VISIBILITY_PRESET` and `VISIBILITY_INLINES_HIDDEN` and a generated export
+header.
+
+The `C_VISIBILITY_PRESET` and `CXX_VISIBILITY_PRESET` target properties can be used to configure the default visibility
+of symbols in C and C++ code. The `VISIBILITY_INLINES_HIDDEN` property can be used to configure the visibility of
+inline functions. The `VISIBILITY_INLINES_HIDDEN` property is only supported for C++ code.
+
+The default visibility should be configured to hidden and symbols should be explicitly exported using the export
+marcos from a generated export header. The export header can be generated using the CMake function
+`generate_export_header`. Every library should have its own export header.
+
+For shared libraries, this can be done using the following CMake code:
+
+```cmake
+add_library(my_lib SHARED
+ src/my_lib.c)
+set_target_properties(my_lib PROPERTIES
+ C_VISIBILITY_PRESET hidden
+ #For C++ shared libraries also configure CXX_VISIBILITY_PRESET
+ CXX_VISIBILITY_PRESET hidden
+ VISIBILITY_INLINES_HIDDEN ON
+ OUTPUT_NAME celix_my_lib)
+target_include_directories(my_lib
+ PUBLIC
+ $<BUILD_INTERFACE:${CMAKE_BINARY_DIR}/celix/gen/includes/my_lib>
+ PRIVATE
+ src)
+
+#generate export header
+generate_export_header(my_lib
+ BASE_NAME "CELIX_MY_LIB"
+ EXPORT_FILE_NAME "${CMAKE_BINARY_DIR}/celix/gen/includes/my_lib/celix_my_lib_export.h")
+
+#install
+install(TARGETS my_lib EXPORT celix LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+ INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/celix_my_lib)
+install(DIRECTORY include/
+ DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/celix_my_lib)
+install(DIRECTORY ${CMAKE_BINARY_DIR}/celix/gen/includes/my_lib/
+ DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/celix_my_lib)
+```
+
+### Configuring Symbol Visibility for C/C++ Bundles
+
+For bundle, symbol visibility will default be configured to hidden. This can be default by providing
+the `DO_NOT_CONFIGURE_SYMBOL_VISIBILITY` option to the CMake `add_celix_bundle` function.
+
+If symbol visibility is not configured in the `add_celix_bundle`, symbol visibility should be configured the same
+way as a shared library.
+
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+## Branch naming
+
+- Prefix feature branches with `feature/`, hotfix branches with `hotfix/`, bugfix branches with `bugfix/`
+ and release branches with `release/`.
+- If you are working on an issue, prefix the branch name with the issue number. E.g., `feature/1234-add-feature`.
+- Hotfix branches are for urgent fixes that need to be applied as soon as possible.
+- Use short and descriptive branch names.
+
+## Commit Messages
+
+- Utilize the imperative mood when writing commit messages (e.g., "Add feature" instead of "Adds feature"
+ or "Added feature"). This style aligns with git's auto-generated messages for merge commits or revert actions.
+- Ensure that commit messages are descriptive and provide meaningful context.
+- Keep the first line of the commit message concise, ideally under 50 characters.
+ This summary line serves as a quick overview of the change and should be easy to read in git logs.
+- If more context is needed, separate the summary line from the body with a blank line.
+ The body can provide additional details, explanations, or reasoning behind the changes.
+ Aim to keep each line of the commit message body wrapped at around 72 characters for optimal readability.
+- Use bullet points, numbered lists, or other formatting conventions when listing multiple changes or points in the
+ commit message body to improve readability.
+- When applicable, reference related issues, bug reports, or pull requests in the commit message body to
+ provide additional context and establish connections between the commit and the larger project.
+ - If your commit fixes, closes, or resolves an issue, use one of these keywords followed by the issue number
+ (e.g., "fixes #42", "closes #42", or "resolves #42").
+ - If you want to reference an issue without closing it, simply mention the issue number
+ (e.g., "related to #42" or "#42").
+
+## Benchmarking
+
+- When needed, use benchmarking to measure performance.
+- Use the Google Benchmark framework for benchmarking.
Review Comment:
To keep the external libs a bit more manageable. If there is a good reason to use a different benchmark lib, I see no problem with updating the guidlines.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "pnoltes (via GitHub)" <gi...@apache.org>.
pnoltes commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1194931033
##########
documents/development/README.md:
##########
@@ -0,0 +1,537 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
Review Comment:
IMO updating the guidelines, this should be a living document.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "pnoltes (via GitHub)" <gi...@apache.org>.
pnoltes commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1187704519
##########
documents/development/README.md:
##########
@@ -0,0 +1,539 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
+- Add a `static constexpr const char * const VERSION` to the service class, for the service version.
+
+### C++ Bundles
+
+- Use `CamelCase` for C++ bundle target names.
+- Do _not_ use a `Celix` prefix for C++ bundle target names.
+- Use `celix::` prefixed aliases for C++ bundle targets.
+- Use `CamelCase` for C++ bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C++ bundle targets.
+- Use `Apache_Celix_` prefix for C++ bundle symbolic names.
+- Use `Apache Celix ` prefix for C++ bundle names.
+- Use a `celix_` prefix for C++ bundle filenames.
+- Use a group name starting with `celix/` for C++ bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(MyBundle
+ SOURCES src/MyBundle.cc
+ SYMBOLIC_NAME "Apache_Celix_MyBundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_MyBundle"
+ VERSION "1.0.0"
+ GROUP "celix/MyBundleGroup"
+)
+add_library(celix::MyBundle ALIAS MyBundle)
+```
+
+### Unit Tests Naming
+
+- The test fixture should have a`TestSuite` postfix.
+- The source file should be named after the test fixture name and use a `.cc` extension.
+- Testcase names should use `CamelCase` (starting with a capital) and have a `Test` postfix.
+- When using error injection (one of the `error_injector` libraries) a separate test suite should be used.
+ - A `ErrorInjectionTestSuite` postfix should be used for the test fixture.
+ - The error injection setup should be reset on the `TearDown` function or destructor of the test fixture.
+
+## Comments and Documentation
+
+- Use Doxygen for code documentation.
+- Write comments that explain the purpose of the code, focusing on the "why" rather than the "how".
+- Apply doxygen documentation to all public API's.
+- Use the javadoc style for doxygen documentation.
+- Use `@` instead of `\` for doxygen commands.
+- Start with a `@brief` command and a short description.
+- For `@param` commands also provide in, out, or in/out information.
+
+## Formatting and Indentation
+
+- Use spaces for indentation and use 4 spaces per indentation level.
+- Keep line lengths under 120 characters, if possible, to enhance readability.
+- Place opening braces on the same line as the control statement or function definition,
+ and closing braces on a new line aligned with the control statement or function definition.
+- Use a single space before and after operators and around assignment statements.
+- Add a space after control keywords (`if`, `for`, `while`, etc.) that are followed by a parenthesis.
+- Always use braces ({ }) for control structures, even for single-statement blocks, to prevent errors.
+- Add a space after control keywords (`else`, `do`, etc) that are followed by a brace.
+- Do not add a space after the function name and the opening parenthesis.
+- For new files apply clang-format using the project .clang-format file.
+ - Note that this can be done using a plugin for your IDE or by running `clang-format -i <file>`.
+
+## Control Structures
+
+- Use `if`, `else if`, and `else` statements to handle multiple conditions.
+- Use `switch` statements for multiple conditions with a default case.
+- Use `while` statements for loops that may not execute.
+- Use `do`/`while` statements for loops that must execute at least once.
+- Use `for` statements for loops with a known number of iterations.
+- The use of `goto` is not allowed, except for error handling.
Review Comment:
I agree
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "PengZheng (via GitHub)" <gi...@apache.org>.
PengZheng commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1188670371
##########
documents/development/README.md:
##########
@@ -0,0 +1,539 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
Review Comment:
Related to #510.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "PengZheng (via GitHub)" <gi...@apache.org>.
PengZheng commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1188043963
##########
documents/development/README.md:
##########
@@ -0,0 +1,539 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
+- Add a `static constexpr const char * const VERSION` to the service class, for the service version.
+
+### C++ Bundles
+
+- Use `CamelCase` for C++ bundle target names.
+- Do _not_ use a `Celix` prefix for C++ bundle target names.
+- Use `celix::` prefixed aliases for C++ bundle targets.
+- Use `CamelCase` for C++ bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C++ bundle targets.
+- Use `Apache_Celix_` prefix for C++ bundle symbolic names.
+- Use `Apache Celix ` prefix for C++ bundle names.
+- Use a `celix_` prefix for C++ bundle filenames.
+- Use a group name starting with `celix/` for C++ bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(MyBundle
+ SOURCES src/MyBundle.cc
+ SYMBOLIC_NAME "Apache_Celix_MyBundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_MyBundle"
+ VERSION "1.0.0"
+ GROUP "celix/MyBundleGroup"
+)
+add_library(celix::MyBundle ALIAS MyBundle)
+```
+
+### Unit Tests Naming
+
+- The test fixture should have a`TestSuite` postfix.
+- The source file should be named after the test fixture name and use a `.cc` extension.
+- Testcase names should use `CamelCase` (starting with a capital) and have a `Test` postfix.
+- When using error injection (one of the `error_injector` libraries) a separate test suite should be used.
+ - A `ErrorInjectionTestSuite` postfix should be used for the test fixture.
+ - The error injection setup should be reset on the `TearDown` function or destructor of the test fixture.
+
+## Comments and Documentation
+
+- Use Doxygen for code documentation.
+- Write comments that explain the purpose of the code, focusing on the "why" rather than the "how".
+- Apply doxygen documentation to all public API's.
+- Use the javadoc style for doxygen documentation.
+- Use `@` instead of `\` for doxygen commands.
+- Start with a `@brief` command and a short description.
+- For `@param` commands also provide in, out, or in/out information.
Review Comment:
And its `ERRORS` section.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "PengZheng (via GitHub)" <gi...@apache.org>.
PengZheng commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1188603128
##########
documents/development/README.md:
##########
@@ -0,0 +1,539 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
+- Add a `static constexpr const char * const VERSION` to the service class, for the service version.
+
+### C++ Bundles
+
+- Use `CamelCase` for C++ bundle target names.
+- Do _not_ use a `Celix` prefix for C++ bundle target names.
+- Use `celix::` prefixed aliases for C++ bundle targets.
+- Use `CamelCase` for C++ bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C++ bundle targets.
+- Use `Apache_Celix_` prefix for C++ bundle symbolic names.
+- Use `Apache Celix ` prefix for C++ bundle names.
+- Use a `celix_` prefix for C++ bundle filenames.
+- Use a group name starting with `celix/` for C++ bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(MyBundle
+ SOURCES src/MyBundle.cc
+ SYMBOLIC_NAME "Apache_Celix_MyBundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_MyBundle"
+ VERSION "1.0.0"
+ GROUP "celix/MyBundleGroup"
+)
+add_library(celix::MyBundle ALIAS MyBundle)
+```
+
+### Unit Tests Naming
+
+- The test fixture should have a`TestSuite` postfix.
+- The source file should be named after the test fixture name and use a `.cc` extension.
+- Testcase names should use `CamelCase` (starting with a capital) and have a `Test` postfix.
+- When using error injection (one of the `error_injector` libraries) a separate test suite should be used.
+ - A `ErrorInjectionTestSuite` postfix should be used for the test fixture.
+ - The error injection setup should be reset on the `TearDown` function or destructor of the test fixture.
+
+## Comments and Documentation
+
+- Use Doxygen for code documentation.
Review Comment:
Oops, I'm just against using Doxygen beyond documentation. Specifically it should not be used for comments. We'd better emphasize the difference between documentation and comments. I've encountered guys who just learn Doxygen use it for comments.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "pnoltes (via GitHub)" <gi...@apache.org>.
pnoltes commented on PR #544:
URL: https://github.com/apache/celix/pull/544#issuecomment-1586161987
While I would prefer additional reviewers, this pull request has remained open for an extended period, so I'm going to merge it now. If there are any suggestions for updating the coding conventions, these can be implemented in a separate pull request.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "pnoltes (via GitHub)" <gi...@apache.org>.
pnoltes merged PR #544:
URL: https://github.com/apache/celix/pull/544
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "rlenferink (via GitHub)" <gi...@apache.org>.
rlenferink commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1191566840
##########
documents/development/README.md:
##########
@@ -0,0 +1,537 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
Review Comment:
On L38 the guideline says: `Asterisk `*` should be placed on the variable type name.`
Shouldn't this example be updated?
```suggestion
- Add a `static constexpr const char* const NAME` to the service class, for the service name.
```
https://github.com/apache/celix/pull/544/files#diff-d0ac5fc51b31228f9b373cdcfffe5f1504a7441e294ecdb6258195fecc811386R38
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "WopsS (via GitHub)" <gi...@apache.org>.
WopsS commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1205830146
##########
documents/development/README.md:
##########
@@ -0,0 +1,537 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
Review Comment:
Mostly storage space. By default `enum class` is 4 bytes, if not all values are used then the rest of the space is wasted.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "pnoltes (via GitHub)" <gi...@apache.org>.
pnoltes commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1195620665
##########
.clang-format:
##########
@@ -0,0 +1,27 @@
+BasedOnStyle: LLVM
+IndentWidth: 4
+AllowShortIfStatementsOnASingleLine: false
+AlwaysBreakTemplateDeclarations: Yes
+BinPackArguments: false
+BinPackParameters: false
+BreakBeforeBraces: Attach
+ColumnLimit: 120
+ConstructorInitializerIndentWidth: 4
+Cpp11BracedListStyle: true
+DerivePointerAlignment: false
+IncludeBlocks: Regroup
+KeepEmptyLinesAtTheStartOfBlocks: false
+NamespaceIndentation: None
+PointerAlignment: Right
+ReflowComments: true
+SortIncludes: false
Review Comment:
you are correct, i am still tweaking the clang-format file
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "codecov-commenter (via GitHub)" <gi...@apache.org>.
codecov-commenter commented on PR #544:
URL: https://github.com/apache/celix/pull/544#issuecomment-1537102487
## [Codecov](https://app.codecov.io/gh/apache/celix/pull/544?src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=The+Apache+Software+Foundation) Report
> Merging [#544](https://app.codecov.io/gh/apache/celix/pull/544?src=pr&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=The+Apache+Software+Foundation) (88ea127) into [master](https://app.codecov.io/gh/apache/celix/commit/dd3d35a36806b853db3c6d47a41204487fc41bc9?el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=The+Apache+Software+Foundation) (dd3d35a) will **decrease** coverage by `0.02%`.
> The diff coverage is `n/a`.
```diff
@@ Coverage Diff @@
## master #544 +/- ##
==========================================
- Coverage 77.44% 77.43% -0.02%
==========================================
Files 225 225
Lines 34532 34532
==========================================
- Hits 26744 26739 -5
- Misses 7788 7793 +5
```
[see 5 files with indirect coverage changes](https://app.codecov.io/gh/apache/celix/pull/544/indirect-changes?src=pr&el=tree-more&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=The+Apache+Software+Foundation)
:mega: We’re building smart automated test selection to slash your CI/CD build times. [Learn more](https://about.codecov.io/iterative-testing/?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=The+Apache+Software+Foundation)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "PengZheng (via GitHub)" <gi...@apache.org>.
PengZheng commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1187444600
##########
documents/development/README.md:
##########
@@ -0,0 +1,539 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
Review Comment:
I tried provided .clang-format, and found it does not format code like this.
How about exporting your CLion code style both as .clang-format and IDEA code style XML?
Zhengbao Xu and I can just import your CLion code style XML and other users can use .clang-format.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "PengZheng (via GitHub)" <gi...@apache.org>.
PengZheng commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1187444600
##########
documents/development/README.md:
##########
@@ -0,0 +1,539 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
Review Comment:
I tried provided .clang-format, and found it does not format code like this.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "pnoltes (via GitHub)" <gi...@apache.org>.
pnoltes commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1187696604
##########
documents/development/README.md:
##########
@@ -0,0 +1,539 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
+- Add a `static constexpr const char * const VERSION` to the service class, for the service version.
Review Comment:
True.
Currently, the majority of implementations utilize the SERVICE_NAME and SERVICE_VERSION postfixes.
I find myself somewhat ambivalent on this matter, as a service is essentially an interface implementation registered within the framework under a specific name and a set of properties. IMO an appropriate name should focus on the interface name, and appending "service" to all names might be redundant.
However, crafting a suitable name without employing the term "service" can sometimes prove challenging.
For example I cannot think of a good alternative name for "celix_log_service".
As a result, I am uncertain about which option I prefer:
```
#define FOO_SERVICE_NAME "foo_service"
#define FOO_SERVICE_VERSION "1.0.0"
```
or
```
#define FOO_NAME "foo"
#define FOO_VERSION "1.0.0"
```
WDYT?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "PengZheng (via GitHub)" <gi...@apache.org>.
PengZheng commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1188595290
##########
documents/development/README.md:
##########
@@ -0,0 +1,539 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
+- Add a `static constexpr const char * const VERSION` to the service class, for the service version.
Review Comment:
I prefer removing the redundancy from the name.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "pnoltes (via GitHub)" <gi...@apache.org>.
pnoltes commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1195594309
##########
documents/development/README.md:
##########
@@ -0,0 +1,537 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
Review Comment:
I mean the getter/setter convention used in java code, which originates from the JavaBeans spec.
Will add more clarification
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "pnoltes (via GitHub)" <gi...@apache.org>.
pnoltes commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1195594309
##########
documents/development/README.md:
##########
@@ -0,0 +1,537 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
Review Comment:
I mean the getter/setter convention used in java code, which originates from the JavaBeans spec.
Added more clarification
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "pnoltes (via GitHub)" <gi...@apache.org>.
pnoltes commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1201066516
##########
.clang-format:
##########
@@ -0,0 +1,27 @@
+BasedOnStyle: LLVM
+IndentWidth: 4
+AllowShortIfStatementsOnASingleLine: false
+AlwaysBreakTemplateDeclarations: Yes
+BinPackArguments: false
+BinPackParameters: false
+BreakBeforeBraces: Attach
+ColumnLimit: 120
+ConstructorInitializerIndentWidth: 4
+Cpp11BracedListStyle: true
+DerivePointerAlignment: false
+IncludeBlocks: Regroup
+KeepEmptyLinesAtTheStartOfBlocks: false
+NamespaceIndentation: None
+PointerAlignment: Right
+ReflowComments: true
+SortIncludes: false
+SpaceAfterCStyleCast: false
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeParens: ControlStatements
+SpaceInEmptyParentheses: false
+SpacesBeforeTrailingComments: 1
+SpacesInAngles: Never
+SpacesInCStyleCastParentheses: false
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+AlignEscapedNewlines: Right
Review Comment:
Removed redundant options
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "pnoltes (via GitHub)" <gi...@apache.org>.
pnoltes commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1194927442
##########
documents/development/README.md:
##########
@@ -0,0 +1,539 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
Review Comment:
I will test the clang-format file a bit more
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "PengZheng (via GitHub)" <gi...@apache.org>.
PengZheng commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1195863302
##########
documents/development/README.md:
##########
@@ -0,0 +1,539 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
+- Add a `static constexpr const char * const VERSION` to the service class, for the service version.
+
+### C++ Bundles
+
+- Use `CamelCase` for C++ bundle target names.
+- Do _not_ use a `Celix` prefix for C++ bundle target names.
+- Use `celix::` prefixed aliases for C++ bundle targets.
+- Use `CamelCase` for C++ bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C++ bundle targets.
+- Use `Apache_Celix_` prefix for C++ bundle symbolic names.
+- Use `Apache Celix ` prefix for C++ bundle names.
+- Use a `celix_` prefix for C++ bundle filenames.
+- Use a group name starting with `celix/` for C++ bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(MyBundle
+ SOURCES src/MyBundle.cc
+ SYMBOLIC_NAME "Apache_Celix_MyBundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_MyBundle"
+ VERSION "1.0.0"
+ GROUP "celix/MyBundleGroup"
+)
+add_library(celix::MyBundle ALIAS MyBundle)
+```
+
+### Unit Tests Naming
+
+- The test fixture should have a`TestSuite` postfix.
+- The source file should be named after the test fixture name and use a `.cc` extension.
+- Testcase names should use `CamelCase` (starting with a capital) and have a `Test` postfix.
+- When using error injection (one of the `error_injector` libraries) a separate test suite should be used.
+ - A `ErrorInjectionTestSuite` postfix should be used for the test fixture.
+ - The error injection setup should be reset on the `TearDown` function or destructor of the test fixture.
+
+## Comments and Documentation
+
+- Use Doxygen for code documentation.
+- Write comments that explain the purpose of the code, focusing on the "why" rather than the "how".
+- Apply doxygen documentation to all public API's.
+- Use the javadoc style for doxygen documentation.
+- Use `@` instead of `\` for doxygen commands.
+- Start with a `@brief` command and a short description.
+- For `@param` commands also provide in, out, or in/out information.
+
+## Formatting and Indentation
+
+- Use spaces for indentation and use 4 spaces per indentation level.
+- Keep line lengths under 120 characters, if possible, to enhance readability.
+- Place opening braces on the same line as the control statement or function definition,
+ and closing braces on a new line aligned with the control statement or function definition.
+- Use a single space before and after operators and around assignment statements.
+- Add a space after control keywords (`if`, `for`, `while`, etc.) that are followed by a parenthesis.
+- Always use braces ({ }) for control structures, even for single-statement blocks, to prevent errors.
+- Add a space after control keywords (`else`, `do`, etc) that are followed by a brace.
+- Do not add a space after the function name and the opening parenthesis.
+- For new files apply clang-format using the project .clang-format file.
+ - Note that this can be done using a plugin for your IDE or by running `clang-format -i <file>`.
+
+## Control Structures
+
+- Use `if`, `else if`, and `else` statements to handle multiple conditions.
+- Use `switch` statements for multiple conditions with a default case.
+- Use `while` statements for loops that may not execute.
+- Use `do`/`while` statements for loops that must execute at least once.
+- Use `for` statements for loops with a known number of iterations.
+- The use of `goto` is not allowed, except for error handling.
+- For C, try to prevent deeply nested control structures and prefer early returns or error handling `goto` statements.
+ - To prevent deeply nested control structures, the `CELIX_DO_IF` and `CELIX_GOTO_IF_ERR` macros can also be used.
+
+## Functions and Methods
+
+- Limit functions to a single responsibility or purpose, following the Single Responsibility Principle (SRP).
+- Keep functions short and focused, aiming for a length of fewer than 50 lines.
+- Ensure const correctness.
+- For C functions with a lot of different parameters, consider using an options struct.
+ - An options struct combined with a EMPTY_OPTIONS macro can be used to provide default values and a such
+ options struct can be updated backwards compatible.
+ - An options struct ensure that a lot of parameters can be configured, but also direct set on creation.
+- For C++ functions with a lot of different parameters, consider using a builder pattern.
+ - A builder pattern can be updated backwards compatible.
+ - A builder pattern ensure that a lot of parameters can be configured, but also direct set on construction.
+
+## Error Handling and Logging
+
+- For C++, throw an exception when an error occurs.
+- For C, if memory allocation is needed or another error can occur, ensure that a function returns a value
+ than can be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- Use consistent error handling techniques, such as returning error codes or using designated error handling functions.
+- Log errors, warnings, and other important events using the Apache Celix log helper functions or - for libraries -
+ the `celix_err` (TBD) functionality.
+- Always check for errors and log them.
+- Ensure error handling is correct, using test suite with error injection.
+
+## Error Injection
+
+- Use the Apache Celix error_injector libraries to inject errors in unit tests in a controlled way.
+- Create a separate test suite for error injection tests.
+- Reset error injection setup on the `TearDown` function or destructor of the test fixture.
+- If an - internal or external - function is missing error injection support, add it to the error_injector library.
+ - Try to create small error injector libraries for specific functionality.
Review Comment:
Currently, we don't have automatic module dependency deduction within the same package, which I plan to add in a future PR. Note that we do have automatic module dependency deduction between conan packages, which conan gives us for free. Dependency deduction works by manipulating these CMake options in conanfile so that these mocks won't be built if not needed.
In that future PR, I also want to make our error injectors installable so that they can be reused by our downstream users.
For Celix's own optional module's mock, it can reuse the module's option.
For external library's mock, a separate subproject is needed.
I found that our error injectors is AI-friendly, and can be generated easily by generative-AI without any IP risks.
Large amounts of reusable error injectors will make our users very happy.
For now we don't need mention anything about this in the coding convention.
When that future PR is worked out, we can revisit this topic.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "WopsS (via GitHub)" <gi...@apache.org>.
WopsS commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1205818326
##########
documents/development/README.md:
##########
@@ -0,0 +1,537 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
Review Comment:
That is also good. But I strongly suggest `detail` for private implementation details.
The reason I suggest `detail` is because it is widely used in C++, most libraries (e.g. boost, fmtlib, spdlog) are using the following "convention":
* `libname::` - This is for public API, which includes everything the user of the library is intended to interact with.
* `libname::detail` - This is for implementation details that are not meant to be seen or used directly by the user of the library.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "PengZheng (via GitHub)" <gi...@apache.org>.
PengZheng commented on PR #544:
URL: https://github.com/apache/celix/pull/544#issuecomment-1585652346
If no further comments, I suggest give the clang-format file a try. @xuzhenbao
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "PengZheng (via GitHub)" <gi...@apache.org>.
PengZheng commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1187003053
##########
documents/development/README.md:
##########
@@ -0,0 +1,539 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
+- Add a `static constexpr const char * const VERSION` to the service class, for the service version.
Review Comment:
As a Celix user who has never written any C++ service, I searched through our C++ examples, but found no example having `NAME` and `VERSION`.
##########
documents/development/README.md:
##########
@@ -0,0 +1,539 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
+- Add a `static constexpr const char * const VERSION` to the service class, for the service version.
+
+### C++ Bundles
+
+- Use `CamelCase` for C++ bundle target names.
+- Do _not_ use a `Celix` prefix for C++ bundle target names.
+- Use `celix::` prefixed aliases for C++ bundle targets.
+- Use `CamelCase` for C++ bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C++ bundle targets.
+- Use `Apache_Celix_` prefix for C++ bundle symbolic names.
+- Use `Apache Celix ` prefix for C++ bundle names.
+- Use a `celix_` prefix for C++ bundle filenames.
+- Use a group name starting with `celix/` for C++ bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(MyBundle
+ SOURCES src/MyBundle.cc
+ SYMBOLIC_NAME "Apache_Celix_MyBundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_MyBundle"
+ VERSION "1.0.0"
+ GROUP "celix/MyBundleGroup"
+)
+add_library(celix::MyBundle ALIAS MyBundle)
+```
+
+### Unit Tests Naming
+
+- The test fixture should have a`TestSuite` postfix.
+- The source file should be named after the test fixture name and use a `.cc` extension.
+- Testcase names should use `CamelCase` (starting with a capital) and have a `Test` postfix.
+- When using error injection (one of the `error_injector` libraries) a separate test suite should be used.
+ - A `ErrorInjectionTestSuite` postfix should be used for the test fixture.
+ - The error injection setup should be reset on the `TearDown` function or destructor of the test fixture.
+
+## Comments and Documentation
+
+- Use Doxygen for code documentation.
+- Write comments that explain the purpose of the code, focusing on the "why" rather than the "how".
+- Apply doxygen documentation to all public API's.
+- Use the javadoc style for doxygen documentation.
+- Use `@` instead of `\` for doxygen commands.
+- Start with a `@brief` command and a short description.
+- For `@param` commands also provide in, out, or in/out information.
Review Comment:
How detailed should `@return` be?
I think `man 2 write` can serve as an example of good return value ducomentation.
##########
documents/development/README.md:
##########
@@ -0,0 +1,539 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
+- Add a `static constexpr const char * const VERSION` to the service class, for the service version.
+
+### C++ Bundles
+
+- Use `CamelCase` for C++ bundle target names.
+- Do _not_ use a `Celix` prefix for C++ bundle target names.
+- Use `celix::` prefixed aliases for C++ bundle targets.
+- Use `CamelCase` for C++ bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C++ bundle targets.
+- Use `Apache_Celix_` prefix for C++ bundle symbolic names.
+- Use `Apache Celix ` prefix for C++ bundle names.
+- Use a `celix_` prefix for C++ bundle filenames.
+- Use a group name starting with `celix/` for C++ bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(MyBundle
+ SOURCES src/MyBundle.cc
+ SYMBOLIC_NAME "Apache_Celix_MyBundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_MyBundle"
+ VERSION "1.0.0"
+ GROUP "celix/MyBundleGroup"
+)
+add_library(celix::MyBundle ALIAS MyBundle)
+```
+
+### Unit Tests Naming
+
+- The test fixture should have a`TestSuite` postfix.
+- The source file should be named after the test fixture name and use a `.cc` extension.
+- Testcase names should use `CamelCase` (starting with a capital) and have a `Test` postfix.
+- When using error injection (one of the `error_injector` libraries) a separate test suite should be used.
+ - A `ErrorInjectionTestSuite` postfix should be used for the test fixture.
+ - The error injection setup should be reset on the `TearDown` function or destructor of the test fixture.
+
+## Comments and Documentation
+
+- Use Doxygen for code documentation.
+- Write comments that explain the purpose of the code, focusing on the "why" rather than the "how".
+- Apply doxygen documentation to all public API's.
+- Use the javadoc style for doxygen documentation.
+- Use `@` instead of `\` for doxygen commands.
+- Start with a `@brief` command and a short description.
+- For `@param` commands also provide in, out, or in/out information.
+
+## Formatting and Indentation
+
+- Use spaces for indentation and use 4 spaces per indentation level.
+- Keep line lengths under 120 characters, if possible, to enhance readability.
+- Place opening braces on the same line as the control statement or function definition,
+ and closing braces on a new line aligned with the control statement or function definition.
+- Use a single space before and after operators and around assignment statements.
+- Add a space after control keywords (`if`, `for`, `while`, etc.) that are followed by a parenthesis.
+- Always use braces ({ }) for control structures, even for single-statement blocks, to prevent errors.
+- Add a space after control keywords (`else`, `do`, etc) that are followed by a brace.
+- Do not add a space after the function name and the opening parenthesis.
+- For new files apply clang-format using the project .clang-format file.
+ - Note that this can be done using a plugin for your IDE or by running `clang-format -i <file>`.
+
+## Control Structures
+
+- Use `if`, `else if`, and `else` statements to handle multiple conditions.
+- Use `switch` statements for multiple conditions with a default case.
+- Use `while` statements for loops that may not execute.
+- Use `do`/`while` statements for loops that must execute at least once.
+- Use `for` statements for loops with a known number of iterations.
+- The use of `goto` is not allowed, except for error handling.
Review Comment:
An example of legitimate use of `goto` for error handling will be very helpful.
##########
documents/development/README.md:
##########
@@ -0,0 +1,539 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
+- Add a `static constexpr const char * const VERSION` to the service class, for the service version.
+
+### C++ Bundles
+
+- Use `CamelCase` for C++ bundle target names.
+- Do _not_ use a `Celix` prefix for C++ bundle target names.
+- Use `celix::` prefixed aliases for C++ bundle targets.
+- Use `CamelCase` for C++ bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C++ bundle targets.
+- Use `Apache_Celix_` prefix for C++ bundle symbolic names.
+- Use `Apache Celix ` prefix for C++ bundle names.
+- Use a `celix_` prefix for C++ bundle filenames.
+- Use a group name starting with `celix/` for C++ bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(MyBundle
+ SOURCES src/MyBundle.cc
+ SYMBOLIC_NAME "Apache_Celix_MyBundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_MyBundle"
+ VERSION "1.0.0"
+ GROUP "celix/MyBundleGroup"
+)
+add_library(celix::MyBundle ALIAS MyBundle)
+```
+
+### Unit Tests Naming
+
+- The test fixture should have a`TestSuite` postfix.
+- The source file should be named after the test fixture name and use a `.cc` extension.
+- Testcase names should use `CamelCase` (starting with a capital) and have a `Test` postfix.
+- When using error injection (one of the `error_injector` libraries) a separate test suite should be used.
+ - A `ErrorInjectionTestSuite` postfix should be used for the test fixture.
+ - The error injection setup should be reset on the `TearDown` function or destructor of the test fixture.
+
+## Comments and Documentation
+
+- Use Doxygen for code documentation.
+- Write comments that explain the purpose of the code, focusing on the "why" rather than the "how".
+- Apply doxygen documentation to all public API's.
+- Use the javadoc style for doxygen documentation.
+- Use `@` instead of `\` for doxygen commands.
+- Start with a `@brief` command and a short description.
+- For `@param` commands also provide in, out, or in/out information.
+
+## Formatting and Indentation
+
+- Use spaces for indentation and use 4 spaces per indentation level.
+- Keep line lengths under 120 characters, if possible, to enhance readability.
+- Place opening braces on the same line as the control statement or function definition,
+ and closing braces on a new line aligned with the control statement or function definition.
+- Use a single space before and after operators and around assignment statements.
+- Add a space after control keywords (`if`, `for`, `while`, etc.) that are followed by a parenthesis.
+- Always use braces ({ }) for control structures, even for single-statement blocks, to prevent errors.
+- Add a space after control keywords (`else`, `do`, etc) that are followed by a brace.
+- Do not add a space after the function name and the opening parenthesis.
+- For new files apply clang-format using the project .clang-format file.
+ - Note that this can be done using a plugin for your IDE or by running `clang-format -i <file>`.
+
+## Control Structures
+
+- Use `if`, `else if`, and `else` statements to handle multiple conditions.
+- Use `switch` statements for multiple conditions with a default case.
+- Use `while` statements for loops that may not execute.
+- Use `do`/`while` statements for loops that must execute at least once.
+- Use `for` statements for loops with a known number of iterations.
+- The use of `goto` is not allowed, except for error handling.
+- For C, try to prevent deeply nested control structures and prefer early returns or error handling `goto` statements.
+ - To prevent deeply nested control structures, the `CELIX_DO_IF` and `CELIX_GOTO_IF_ERR` macros can also be used.
+
+## Functions and Methods
+
+- Limit functions to a single responsibility or purpose, following the Single Responsibility Principle (SRP).
+- Keep functions short and focused, aiming for a length of fewer than 50 lines.
+- Ensure const correctness.
+- For C functions with a lot of different parameters, consider using an options struct.
+ - An options struct combined with a EMPTY_OPTIONS macro can be used to provide default values and a such
+ options struct can be updated backwards compatible.
+ - An options struct ensure that a lot of parameters can be configured, but also direct set on creation.
+- For C++ functions with a lot of different parameters, consider using a builder pattern.
+ - A builder pattern can be updated backwards compatible.
+ - A builder pattern ensure that a lot of parameters can be configured, but also direct set on construction.
+
+## Error Handling and Logging
+
+- For C++, throw an exception when an error occurs.
+- For C, if memory allocation is needed or another error can occur, ensure that a function returns a value
+ than can be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- Use consistent error handling techniques, such as returning error codes or using designated error handling functions.
+- Log errors, warnings, and other important events using the Apache Celix log helper functions or - for libraries -
+ the `celix_err` (TBD) functionality.
+- Always check for errors and log them.
+- Ensure error handling is correct, using test suite with error injection.
Review Comment:
One C specific aspect of error handling may worth mentioning: if we try to create something like an object and that attempt fails, then we need to release all resources (probably using goto pattern to release them in strict reverse order) that have been allocated. `celix_bundleArchive_create` can serve as an example of what should not be done (leaving broken directories on the disk).
##########
documents/development/README.md:
##########
@@ -0,0 +1,539 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
+- Add a `static constexpr const char * const VERSION` to the service class, for the service version.
+
+### C++ Bundles
+
+- Use `CamelCase` for C++ bundle target names.
+- Do _not_ use a `Celix` prefix for C++ bundle target names.
+- Use `celix::` prefixed aliases for C++ bundle targets.
+- Use `CamelCase` for C++ bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C++ bundle targets.
+- Use `Apache_Celix_` prefix for C++ bundle symbolic names.
+- Use `Apache Celix ` prefix for C++ bundle names.
+- Use a `celix_` prefix for C++ bundle filenames.
+- Use a group name starting with `celix/` for C++ bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(MyBundle
+ SOURCES src/MyBundle.cc
+ SYMBOLIC_NAME "Apache_Celix_MyBundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_MyBundle"
+ VERSION "1.0.0"
+ GROUP "celix/MyBundleGroup"
+)
+add_library(celix::MyBundle ALIAS MyBundle)
+```
+
+### Unit Tests Naming
+
+- The test fixture should have a`TestSuite` postfix.
+- The source file should be named after the test fixture name and use a `.cc` extension.
+- Testcase names should use `CamelCase` (starting with a capital) and have a `Test` postfix.
+- When using error injection (one of the `error_injector` libraries) a separate test suite should be used.
+ - A `ErrorInjectionTestSuite` postfix should be used for the test fixture.
+ - The error injection setup should be reset on the `TearDown` function or destructor of the test fixture.
+
+## Comments and Documentation
+
+- Use Doxygen for code documentation.
+- Write comments that explain the purpose of the code, focusing on the "why" rather than the "how".
+- Apply doxygen documentation to all public API's.
+- Use the javadoc style for doxygen documentation.
+- Use `@` instead of `\` for doxygen commands.
+- Start with a `@brief` command and a short description.
+- For `@param` commands also provide in, out, or in/out information.
+
+## Formatting and Indentation
+
+- Use spaces for indentation and use 4 spaces per indentation level.
+- Keep line lengths under 120 characters, if possible, to enhance readability.
+- Place opening braces on the same line as the control statement or function definition,
+ and closing braces on a new line aligned with the control statement or function definition.
+- Use a single space before and after operators and around assignment statements.
+- Add a space after control keywords (`if`, `for`, `while`, etc.) that are followed by a parenthesis.
+- Always use braces ({ }) for control structures, even for single-statement blocks, to prevent errors.
+- Add a space after control keywords (`else`, `do`, etc) that are followed by a brace.
+- Do not add a space after the function name and the opening parenthesis.
+- For new files apply clang-format using the project .clang-format file.
+ - Note that this can be done using a plugin for your IDE or by running `clang-format -i <file>`.
+
+## Control Structures
+
+- Use `if`, `else if`, and `else` statements to handle multiple conditions.
+- Use `switch` statements for multiple conditions with a default case.
+- Use `while` statements for loops that may not execute.
+- Use `do`/`while` statements for loops that must execute at least once.
+- Use `for` statements for loops with a known number of iterations.
+- The use of `goto` is not allowed, except for error handling.
+- For C, try to prevent deeply nested control structures and prefer early returns or error handling `goto` statements.
+ - To prevent deeply nested control structures, the `CELIX_DO_IF` and `CELIX_GOTO_IF_ERR` macros can also be used.
+
+## Functions and Methods
+
+- Limit functions to a single responsibility or purpose, following the Single Responsibility Principle (SRP).
+- Keep functions short and focused, aiming for a length of fewer than 50 lines.
+- Ensure const correctness.
+- For C functions with a lot of different parameters, consider using an options struct.
+ - An options struct combined with a EMPTY_OPTIONS macro can be used to provide default values and a such
+ options struct can be updated backwards compatible.
+ - An options struct ensure that a lot of parameters can be configured, but also direct set on creation.
+- For C++ functions with a lot of different parameters, consider using a builder pattern.
+ - A builder pattern can be updated backwards compatible.
+ - A builder pattern ensure that a lot of parameters can be configured, but also direct set on construction.
+
+## Error Handling and Logging
+
+- For C++, throw an exception when an error occurs.
+- For C, if memory allocation is needed or another error can occur, ensure that a function returns a value
+ than can be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- Use consistent error handling techniques, such as returning error codes or using designated error handling functions.
+- Log errors, warnings, and other important events using the Apache Celix log helper functions or - for libraries -
+ the `celix_err` (TBD) functionality.
+- Always check for errors and log them.
+- Ensure error handling is correct, using test suite with error injection.
+
+## Error Injection
+
+- Use the Apache Celix error_injector libraries to inject errors in unit tests in a controlled way.
+- Create a separate test suite for error injection tests.
+- Reset error injection setup on the `TearDown` function or destructor of the test fixture.
+- If an - internal or external - function is missing error injection support, add it to the error_injector library.
+ - Try to create small error injector libraries for specific functionality.
+
+## Unit Test Approach
+
+- Use the Google Test framework for unit tests.
+- Use the Google Mock framework for mocking.
+- Use the Apache Celix error_injector libraries to inject errors in unit tests in a controlled way.
+- Test bundles by installing them in a programmatically created framework.
+- Test bundles by using their provided services and used services.
+- In most cases, libraries can be tested using a white box approach and bundles can be tested using a black box approach.
+- For libraries that are tested with the Apache Celix error_injector libraries or require access to private/hidden
+ functions, a separate "code under test" static library should be created.
+ This library should not hide its symbols and should have a `_cut` postfix.
+
+
+```cmake
+set(MY_LIB_SOURCES ...)
+set(MY_LIB_PUBLIC_LIBS ...)
+set(MY_LIB_PRIVATE_LIBS ...)
+add_library(my_lib SHARED ${MY_LIB_SOURCES})
+target_link_libraries(my_lib PUBLIC ${MY_LIB_PUBLIC_LIBS} PRIVATE ${MY_LIB_PRIVATE_LIBS})
+celix_target_hide_symbols(my_lib)
+...
+
+if (ENABLE_TESTING)
+ add_library(my_lib_cut STATIC ${MY_LIB_SOURCES})
+ target_link_libraries(my_lib PUBLIC ${MY_LIB_PUBLIC_LIBS} PRIVATE ${MY_LIB_PRIVATE_LIBS})
Review Comment:
```suggestion
target_link_libraries(my_lib_cut PUBLIC ${MY_LIB_PUBLIC_LIBS} ${MY_LIB_PRIVATE_LIBS})
```
Typo corrected. Also I tend to make everything PUBLIC for code under test for convenience, but not against the contrary.
##########
documents/development/README.md:
##########
@@ -0,0 +1,539 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
+- Add a `static constexpr const char * const VERSION` to the service class, for the service version.
+
+### C++ Bundles
+
+- Use `CamelCase` for C++ bundle target names.
+- Do _not_ use a `Celix` prefix for C++ bundle target names.
+- Use `celix::` prefixed aliases for C++ bundle targets.
+- Use `CamelCase` for C++ bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C++ bundle targets.
+- Use `Apache_Celix_` prefix for C++ bundle symbolic names.
+- Use `Apache Celix ` prefix for C++ bundle names.
+- Use a `celix_` prefix for C++ bundle filenames.
+- Use a group name starting with `celix/` for C++ bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(MyBundle
+ SOURCES src/MyBundle.cc
+ SYMBOLIC_NAME "Apache_Celix_MyBundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_MyBundle"
+ VERSION "1.0.0"
+ GROUP "celix/MyBundleGroup"
+)
+add_library(celix::MyBundle ALIAS MyBundle)
+```
+
+### Unit Tests Naming
+
+- The test fixture should have a`TestSuite` postfix.
+- The source file should be named after the test fixture name and use a `.cc` extension.
+- Testcase names should use `CamelCase` (starting with a capital) and have a `Test` postfix.
+- When using error injection (one of the `error_injector` libraries) a separate test suite should be used.
+ - A `ErrorInjectionTestSuite` postfix should be used for the test fixture.
+ - The error injection setup should be reset on the `TearDown` function or destructor of the test fixture.
+
+## Comments and Documentation
+
+- Use Doxygen for code documentation.
Review Comment:
Should use of Doxygen be restricted to API documentation? I've encounter guys who use Doxygen everywhere.
##########
documents/development/README.md:
##########
@@ -0,0 +1,539 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
Review Comment:
If we are not satisfied with being an in-process service-oriented programming environment, then remote services should also be considered. For what I know, RSA has very specific requirements for `celix_status_t` return value and parameter passing.
Service designer should consider these requirements from the very beginning.
For our RSA to be more successful, we should generate descriptor from the more readable header file automatically and make RSA available to other languaes like javascript and Java. Of course these should belong to another extended discussion.
##########
documents/development/README.md:
##########
@@ -0,0 +1,539 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
+- Add a `static constexpr const char * const VERSION` to the service class, for the service version.
+
+### C++ Bundles
+
+- Use `CamelCase` for C++ bundle target names.
+- Do _not_ use a `Celix` prefix for C++ bundle target names.
+- Use `celix::` prefixed aliases for C++ bundle targets.
+- Use `CamelCase` for C++ bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C++ bundle targets.
+- Use `Apache_Celix_` prefix for C++ bundle symbolic names.
+- Use `Apache Celix ` prefix for C++ bundle names.
+- Use a `celix_` prefix for C++ bundle filenames.
+- Use a group name starting with `celix/` for C++ bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(MyBundle
+ SOURCES src/MyBundle.cc
+ SYMBOLIC_NAME "Apache_Celix_MyBundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_MyBundle"
+ VERSION "1.0.0"
+ GROUP "celix/MyBundleGroup"
+)
+add_library(celix::MyBundle ALIAS MyBundle)
+```
+
+### Unit Tests Naming
+
+- The test fixture should have a`TestSuite` postfix.
+- The source file should be named after the test fixture name and use a `.cc` extension.
+- Testcase names should use `CamelCase` (starting with a capital) and have a `Test` postfix.
+- When using error injection (one of the `error_injector` libraries) a separate test suite should be used.
+ - A `ErrorInjectionTestSuite` postfix should be used for the test fixture.
+ - The error injection setup should be reset on the `TearDown` function or destructor of the test fixture.
+
+## Comments and Documentation
+
+- Use Doxygen for code documentation.
+- Write comments that explain the purpose of the code, focusing on the "why" rather than the "how".
+- Apply doxygen documentation to all public API's.
+- Use the javadoc style for doxygen documentation.
+- Use `@` instead of `\` for doxygen commands.
+- Start with a `@brief` command and a short description.
+- For `@param` commands also provide in, out, or in/out information.
+
+## Formatting and Indentation
+
+- Use spaces for indentation and use 4 spaces per indentation level.
+- Keep line lengths under 120 characters, if possible, to enhance readability.
+- Place opening braces on the same line as the control statement or function definition,
+ and closing braces on a new line aligned with the control statement or function definition.
+- Use a single space before and after operators and around assignment statements.
+- Add a space after control keywords (`if`, `for`, `while`, etc.) that are followed by a parenthesis.
+- Always use braces ({ }) for control structures, even for single-statement blocks, to prevent errors.
+- Add a space after control keywords (`else`, `do`, etc) that are followed by a brace.
+- Do not add a space after the function name and the opening parenthesis.
+- For new files apply clang-format using the project .clang-format file.
+ - Note that this can be done using a plugin for your IDE or by running `clang-format -i <file>`.
+
+## Control Structures
+
+- Use `if`, `else if`, and `else` statements to handle multiple conditions.
+- Use `switch` statements for multiple conditions with a default case.
+- Use `while` statements for loops that may not execute.
+- Use `do`/`while` statements for loops that must execute at least once.
+- Use `for` statements for loops with a known number of iterations.
+- The use of `goto` is not allowed, except for error handling.
+- For C, try to prevent deeply nested control structures and prefer early returns or error handling `goto` statements.
+ - To prevent deeply nested control structures, the `CELIX_DO_IF` and `CELIX_GOTO_IF_ERR` macros can also be used.
+
+## Functions and Methods
+
+- Limit functions to a single responsibility or purpose, following the Single Responsibility Principle (SRP).
+- Keep functions short and focused, aiming for a length of fewer than 50 lines.
+- Ensure const correctness.
+- For C functions with a lot of different parameters, consider using an options struct.
+ - An options struct combined with a EMPTY_OPTIONS macro can be used to provide default values and a such
+ options struct can be updated backwards compatible.
+ - An options struct ensure that a lot of parameters can be configured, but also direct set on creation.
+- For C++ functions with a lot of different parameters, consider using a builder pattern.
+ - A builder pattern can be updated backwards compatible.
+ - A builder pattern ensure that a lot of parameters can be configured, but also direct set on construction.
+
+## Error Handling and Logging
+
+- For C++, throw an exception when an error occurs.
+- For C, if memory allocation is needed or another error can occur, ensure that a function returns a value
+ than can be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- Use consistent error handling techniques, such as returning error codes or using designated error handling functions.
+- Log errors, warnings, and other important events using the Apache Celix log helper functions or - for libraries -
Review Comment:
We may need to establish a common interpretation of logging levels like the following link.
A common mistake is to misuse `CELIX_LOG_LEVEL_ERROR` for non-error conditions.
https://stackoverflow.com/questions/2031163/when-to-use-the-different-log-levels
##########
documents/development/README.md:
##########
@@ -0,0 +1,539 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
+- Add a `static constexpr const char * const VERSION` to the service class, for the service version.
+
+### C++ Bundles
+
+- Use `CamelCase` for C++ bundle target names.
+- Do _not_ use a `Celix` prefix for C++ bundle target names.
+- Use `celix::` prefixed aliases for C++ bundle targets.
+- Use `CamelCase` for C++ bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C++ bundle targets.
+- Use `Apache_Celix_` prefix for C++ bundle symbolic names.
+- Use `Apache Celix ` prefix for C++ bundle names.
+- Use a `celix_` prefix for C++ bundle filenames.
+- Use a group name starting with `celix/` for C++ bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(MyBundle
+ SOURCES src/MyBundle.cc
+ SYMBOLIC_NAME "Apache_Celix_MyBundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_MyBundle"
+ VERSION "1.0.0"
+ GROUP "celix/MyBundleGroup"
+)
+add_library(celix::MyBundle ALIAS MyBundle)
+```
+
+### Unit Tests Naming
+
+- The test fixture should have a`TestSuite` postfix.
+- The source file should be named after the test fixture name and use a `.cc` extension.
+- Testcase names should use `CamelCase` (starting with a capital) and have a `Test` postfix.
+- When using error injection (one of the `error_injector` libraries) a separate test suite should be used.
+ - A `ErrorInjectionTestSuite` postfix should be used for the test fixture.
+ - The error injection setup should be reset on the `TearDown` function or destructor of the test fixture.
+
+## Comments and Documentation
+
+- Use Doxygen for code documentation.
+- Write comments that explain the purpose of the code, focusing on the "why" rather than the "how".
+- Apply doxygen documentation to all public API's.
+- Use the javadoc style for doxygen documentation.
+- Use `@` instead of `\` for doxygen commands.
+- Start with a `@brief` command and a short description.
+- For `@param` commands also provide in, out, or in/out information.
+
+## Formatting and Indentation
+
+- Use spaces for indentation and use 4 spaces per indentation level.
+- Keep line lengths under 120 characters, if possible, to enhance readability.
+- Place opening braces on the same line as the control statement or function definition,
+ and closing braces on a new line aligned with the control statement or function definition.
+- Use a single space before and after operators and around assignment statements.
+- Add a space after control keywords (`if`, `for`, `while`, etc.) that are followed by a parenthesis.
+- Always use braces ({ }) for control structures, even for single-statement blocks, to prevent errors.
+- Add a space after control keywords (`else`, `do`, etc) that are followed by a brace.
+- Do not add a space after the function name and the opening parenthesis.
+- For new files apply clang-format using the project .clang-format file.
+ - Note that this can be done using a plugin for your IDE or by running `clang-format -i <file>`.
+
+## Control Structures
+
+- Use `if`, `else if`, and `else` statements to handle multiple conditions.
+- Use `switch` statements for multiple conditions with a default case.
+- Use `while` statements for loops that may not execute.
+- Use `do`/`while` statements for loops that must execute at least once.
+- Use `for` statements for loops with a known number of iterations.
+- The use of `goto` is not allowed, except for error handling.
+- For C, try to prevent deeply nested control structures and prefer early returns or error handling `goto` statements.
+ - To prevent deeply nested control structures, the `CELIX_DO_IF` and `CELIX_GOTO_IF_ERR` macros can also be used.
+
+## Functions and Methods
+
+- Limit functions to a single responsibility or purpose, following the Single Responsibility Principle (SRP).
+- Keep functions short and focused, aiming for a length of fewer than 50 lines.
+- Ensure const correctness.
+- For C functions with a lot of different parameters, consider using an options struct.
+ - An options struct combined with a EMPTY_OPTIONS macro can be used to provide default values and a such
+ options struct can be updated backwards compatible.
+ - An options struct ensure that a lot of parameters can be configured, but also direct set on creation.
+- For C++ functions with a lot of different parameters, consider using a builder pattern.
+ - A builder pattern can be updated backwards compatible.
+ - A builder pattern ensure that a lot of parameters can be configured, but also direct set on construction.
+
+## Error Handling and Logging
+
+- For C++, throw an exception when an error occurs.
+- For C, if memory allocation is needed or another error can occur, ensure that a function returns a value
+ than can be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- Use consistent error handling techniques, such as returning error codes or using designated error handling functions.
+- Log errors, warnings, and other important events using the Apache Celix log helper functions or - for libraries -
+ the `celix_err` (TBD) functionality.
+- Always check for errors and log them.
+- Ensure error handling is correct, using test suite with error injection.
+
+## Error Injection
+
+- Use the Apache Celix error_injector libraries to inject errors in unit tests in a controlled way.
+- Create a separate test suite for error injection tests.
+- Reset error injection setup on the `TearDown` function or destructor of the test fixture.
+- If an - internal or external - function is missing error injection support, add it to the error_injector library.
+ - Try to create small error injector libraries for specific functionality.
+
+## Unit Test Approach
+
+- Use the Google Test framework for unit tests.
+- Use the Google Mock framework for mocking.
+- Use the Apache Celix error_injector libraries to inject errors in unit tests in a controlled way.
+- Test bundles by installing them in a programmatically created framework.
+- Test bundles by using their provided services and used services.
+- In most cases, libraries can be tested using a white box approach and bundles can be tested using a black box approach.
+- For libraries that are tested with the Apache Celix error_injector libraries or require access to private/hidden
+ functions, a separate "code under test" static library should be created.
+ This library should not hide its symbols and should have a `_cut` postfix.
+
+
+```cmake
+set(MY_LIB_SOURCES ...)
+set(MY_LIB_PUBLIC_LIBS ...)
+set(MY_LIB_PRIVATE_LIBS ...)
+add_library(my_lib SHARED ${MY_LIB_SOURCES})
+target_link_libraries(my_lib PUBLIC ${MY_LIB_PUBLIC_LIBS} PRIVATE ${MY_LIB_PRIVATE_LIBS})
+celix_target_hide_symbols(my_lib)
+...
+
+if (ENABLE_TESTING)
+ add_library(my_lib_cut STATIC ${MY_LIB_SOURCES})
+ target_link_libraries(my_lib PUBLIC ${MY_LIB_PUBLIC_LIBS} PRIVATE ${MY_LIB_PRIVATE_LIBS})
+ target_include_directories(my_lib PUBLIC
+ ${CMAKE_CURRENT_LIST_DIR}/src
+ ${CMAKE_CURRENT_LIST_DIR}/include
+ ${CMAKE_BINARY_DIR}/celix/gen/includes/my_lib
+ )
+endif ()
+```
+
+## Supported C and C++ Standards
+
+- C libraries should support C99. (TBD or C11))
+- C++ libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Unit test code can be written in C++17.
+
+## Library target properties
+
+For C and C++ shared libraries, the following target properties should be set:
+ - `VERSION` should be set to the library version.
+ - `SOVERSION` should be set to the library major version.
+ - `OUTPUT_NAME` should be set to the library name and should contain a `celix_` prefix.
+
+```cmake
+add_library(my_lib SHARED
+ src/my_lib.c)
+set_target_properties(my_lib
+ PROPERTIES
+ VERSION 1.0.0
+ SOVERSION 1
+ OUTPUT_NAME celix_my_lib)
+```
+
+For C and C++ static libraries, the following target properties should be set:
+ - `POSITION_INDEPENDENT_CODE` should be set to `ON` for static libraries.
+ - `OUTPUT_NAME` should be set to the library name and should contain a `celix_` prefix.
+
+```cmake
+add_library(my_lib STATIC
+ src/my_lib.c)
+set_target_properties(my_lib
+ PROPERTIES
+ POSITION_INDEPENDENT_CODE ON
+ OUTPUT_NAME celix_my_lib)
+```
+
+## Symbol Visibility
+
+- Header-only (INTERFACE) libraries should not configure symbol visibility.
+- Shared and static libraries should configure symbol visibility.
+ - Static library meant to be linked as PRIVATE should hide symbols.
+- Bundles should configure symbol visibility (this is done by default).
+
+### Configuring Symbol Visibility for C/C++ Libraries
+
+For Apache Celix shared libraries, symbol visibility should be configured using the CMake target
+properties `C_VISIBILITY_PRESET`, `CXX_VISIBILITY_PRESET` and `VISIBILITY_INLINES_HIDDEN` and a generated export
+header.
+
+The `C_VISIBILITY_PRESET` and `CXX_VISIBILITY_PRESET` target properties can be used to configure the default visibility
+of symbols in C and C++ code. The `VISIBILITY_INLINES_HIDDEN` property can be used to configure the visibility of
+inline functions. The `VISIBILITY_INLINES_HIDDEN` property is only supported for C++ code.
+
+The default visibility should be configured to hidden and symbols should be explicitly exported using the export
+marcos from a generated export header. The export header can be generated using the CMake function
+`generate_export_header`. Every library should have its own export header.
+
+For shared libraries, this can be done using the following CMake code:
+
+```cmake
+add_library(my_lib SHARED
+ src/my_lib.c)
+set_target_properties(my_lib PROPERTIES
+ C_VISIBILITY_PRESET hidden
+ #For C++ shared libraries also configure CXX_VISIBILITY_PRESET
+ CXX_VISIBILITY_PRESET hidden
+ VISIBILITY_INLINES_HIDDEN ON
+ OUTPUT_NAME celix_my_lib)
+target_include_directories(my_lib
+ PUBLIC
+ $<BUILD_INTERFACE:${CMAKE_BINARY_DIR}/celix/gen/includes/my_lib>
+ $<INSTALL_INTERFACE:include/celix_my_lib>
Review Comment:
```suggestion
```
I think `INSTALL_INTERFACE` is redundant, since `INCLUDES DESTINATION` in install already sets the include directory for the my_lib target.
##########
documents/development/README.md:
##########
@@ -0,0 +1,539 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
+- Add a `static constexpr const char * const VERSION` to the service class, for the service version.
+
+### C++ Bundles
+
+- Use `CamelCase` for C++ bundle target names.
+- Do _not_ use a `Celix` prefix for C++ bundle target names.
+- Use `celix::` prefixed aliases for C++ bundle targets.
+- Use `CamelCase` for C++ bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C++ bundle targets.
+- Use `Apache_Celix_` prefix for C++ bundle symbolic names.
+- Use `Apache Celix ` prefix for C++ bundle names.
+- Use a `celix_` prefix for C++ bundle filenames.
+- Use a group name starting with `celix/` for C++ bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(MyBundle
+ SOURCES src/MyBundle.cc
+ SYMBOLIC_NAME "Apache_Celix_MyBundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_MyBundle"
+ VERSION "1.0.0"
+ GROUP "celix/MyBundleGroup"
+)
+add_library(celix::MyBundle ALIAS MyBundle)
+```
+
+### Unit Tests Naming
+
+- The test fixture should have a`TestSuite` postfix.
+- The source file should be named after the test fixture name and use a `.cc` extension.
+- Testcase names should use `CamelCase` (starting with a capital) and have a `Test` postfix.
+- When using error injection (one of the `error_injector` libraries) a separate test suite should be used.
+ - A `ErrorInjectionTestSuite` postfix should be used for the test fixture.
+ - The error injection setup should be reset on the `TearDown` function or destructor of the test fixture.
+
+## Comments and Documentation
+
+- Use Doxygen for code documentation.
+- Write comments that explain the purpose of the code, focusing on the "why" rather than the "how".
+- Apply doxygen documentation to all public API's.
+- Use the javadoc style for doxygen documentation.
+- Use `@` instead of `\` for doxygen commands.
+- Start with a `@brief` command and a short description.
+- For `@param` commands also provide in, out, or in/out information.
+
+## Formatting and Indentation
+
+- Use spaces for indentation and use 4 spaces per indentation level.
+- Keep line lengths under 120 characters, if possible, to enhance readability.
+- Place opening braces on the same line as the control statement or function definition,
+ and closing braces on a new line aligned with the control statement or function definition.
+- Use a single space before and after operators and around assignment statements.
+- Add a space after control keywords (`if`, `for`, `while`, etc.) that are followed by a parenthesis.
+- Always use braces ({ }) for control structures, even for single-statement blocks, to prevent errors.
+- Add a space after control keywords (`else`, `do`, etc) that are followed by a brace.
+- Do not add a space after the function name and the opening parenthesis.
+- For new files apply clang-format using the project .clang-format file.
+ - Note that this can be done using a plugin for your IDE or by running `clang-format -i <file>`.
+
+## Control Structures
+
+- Use `if`, `else if`, and `else` statements to handle multiple conditions.
+- Use `switch` statements for multiple conditions with a default case.
+- Use `while` statements for loops that may not execute.
+- Use `do`/`while` statements for loops that must execute at least once.
+- Use `for` statements for loops with a known number of iterations.
+- The use of `goto` is not allowed, except for error handling.
+- For C, try to prevent deeply nested control structures and prefer early returns or error handling `goto` statements.
+ - To prevent deeply nested control structures, the `CELIX_DO_IF` and `CELIX_GOTO_IF_ERR` macros can also be used.
+
+## Functions and Methods
+
+- Limit functions to a single responsibility or purpose, following the Single Responsibility Principle (SRP).
+- Keep functions short and focused, aiming for a length of fewer than 50 lines.
+- Ensure const correctness.
+- For C functions with a lot of different parameters, consider using an options struct.
+ - An options struct combined with a EMPTY_OPTIONS macro can be used to provide default values and a such
+ options struct can be updated backwards compatible.
+ - An options struct ensure that a lot of parameters can be configured, but also direct set on creation.
+- For C++ functions with a lot of different parameters, consider using a builder pattern.
+ - A builder pattern can be updated backwards compatible.
+ - A builder pattern ensure that a lot of parameters can be configured, but also direct set on construction.
+
+## Error Handling and Logging
+
+- For C++, throw an exception when an error occurs.
+- For C, if memory allocation is needed or another error can occur, ensure that a function returns a value
+ than can be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- Use consistent error handling techniques, such as returning error codes or using designated error handling functions.
+- Log errors, warnings, and other important events using the Apache Celix log helper functions or - for libraries -
+ the `celix_err` (TBD) functionality.
+- Always check for errors and log them.
+- Ensure error handling is correct, using test suite with error injection.
+
+## Error Injection
+
+- Use the Apache Celix error_injector libraries to inject errors in unit tests in a controlled way.
+- Create a separate test suite for error injection tests.
+- Reset error injection setup on the `TearDown` function or destructor of the test fixture.
+- If an - internal or external - function is missing error injection support, add it to the error_injector library.
+ - Try to create small error injector libraries for specific functionality.
+
+## Unit Test Approach
+
+- Use the Google Test framework for unit tests.
+- Use the Google Mock framework for mocking.
+- Use the Apache Celix error_injector libraries to inject errors in unit tests in a controlled way.
+- Test bundles by installing them in a programmatically created framework.
+- Test bundles by using their provided services and used services.
+- In most cases, libraries can be tested using a white box approach and bundles can be tested using a black box approach.
+- For libraries that are tested with the Apache Celix error_injector libraries or require access to private/hidden
Review Comment:
I also do this when unit-testing bundles, see rsa_shm for an example. Of course integrating bundles, a block box approach is used.
##########
documents/development/README.md:
##########
@@ -0,0 +1,539 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
+- Add a `static constexpr const char * const VERSION` to the service class, for the service version.
+
+### C++ Bundles
+
+- Use `CamelCase` for C++ bundle target names.
+- Do _not_ use a `Celix` prefix for C++ bundle target names.
+- Use `celix::` prefixed aliases for C++ bundle targets.
+- Use `CamelCase` for C++ bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C++ bundle targets.
+- Use `Apache_Celix_` prefix for C++ bundle symbolic names.
+- Use `Apache Celix ` prefix for C++ bundle names.
+- Use a `celix_` prefix for C++ bundle filenames.
+- Use a group name starting with `celix/` for C++ bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(MyBundle
+ SOURCES src/MyBundle.cc
+ SYMBOLIC_NAME "Apache_Celix_MyBundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_MyBundle"
+ VERSION "1.0.0"
+ GROUP "celix/MyBundleGroup"
+)
+add_library(celix::MyBundle ALIAS MyBundle)
+```
+
+### Unit Tests Naming
+
+- The test fixture should have a`TestSuite` postfix.
+- The source file should be named after the test fixture name and use a `.cc` extension.
+- Testcase names should use `CamelCase` (starting with a capital) and have a `Test` postfix.
+- When using error injection (one of the `error_injector` libraries) a separate test suite should be used.
+ - A `ErrorInjectionTestSuite` postfix should be used for the test fixture.
+ - The error injection setup should be reset on the `TearDown` function or destructor of the test fixture.
+
+## Comments and Documentation
+
+- Use Doxygen for code documentation.
+- Write comments that explain the purpose of the code, focusing on the "why" rather than the "how".
+- Apply doxygen documentation to all public API's.
+- Use the javadoc style for doxygen documentation.
+- Use `@` instead of `\` for doxygen commands.
+- Start with a `@brief` command and a short description.
+- For `@param` commands also provide in, out, or in/out information.
+
+## Formatting and Indentation
+
+- Use spaces for indentation and use 4 spaces per indentation level.
+- Keep line lengths under 120 characters, if possible, to enhance readability.
+- Place opening braces on the same line as the control statement or function definition,
+ and closing braces on a new line aligned with the control statement or function definition.
+- Use a single space before and after operators and around assignment statements.
+- Add a space after control keywords (`if`, `for`, `while`, etc.) that are followed by a parenthesis.
+- Always use braces ({ }) for control structures, even for single-statement blocks, to prevent errors.
+- Add a space after control keywords (`else`, `do`, etc) that are followed by a brace.
+- Do not add a space after the function name and the opening parenthesis.
+- For new files apply clang-format using the project .clang-format file.
+ - Note that this can be done using a plugin for your IDE or by running `clang-format -i <file>`.
+
+## Control Structures
+
+- Use `if`, `else if`, and `else` statements to handle multiple conditions.
+- Use `switch` statements for multiple conditions with a default case.
+- Use `while` statements for loops that may not execute.
+- Use `do`/`while` statements for loops that must execute at least once.
+- Use `for` statements for loops with a known number of iterations.
+- The use of `goto` is not allowed, except for error handling.
+- For C, try to prevent deeply nested control structures and prefer early returns or error handling `goto` statements.
+ - To prevent deeply nested control structures, the `CELIX_DO_IF` and `CELIX_GOTO_IF_ERR` macros can also be used.
+
+## Functions and Methods
+
+- Limit functions to a single responsibility or purpose, following the Single Responsibility Principle (SRP).
+- Keep functions short and focused, aiming for a length of fewer than 50 lines.
+- Ensure const correctness.
+- For C functions with a lot of different parameters, consider using an options struct.
+ - An options struct combined with a EMPTY_OPTIONS macro can be used to provide default values and a such
+ options struct can be updated backwards compatible.
+ - An options struct ensure that a lot of parameters can be configured, but also direct set on creation.
+- For C++ functions with a lot of different parameters, consider using a builder pattern.
+ - A builder pattern can be updated backwards compatible.
+ - A builder pattern ensure that a lot of parameters can be configured, but also direct set on construction.
+
+## Error Handling and Logging
+
+- For C++, throw an exception when an error occurs.
+- For C, if memory allocation is needed or another error can occur, ensure that a function returns a value
+ than can be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- Use consistent error handling techniques, such as returning error codes or using designated error handling functions.
+- Log errors, warnings, and other important events using the Apache Celix log helper functions or - for libraries -
+ the `celix_err` (TBD) functionality.
+- Always check for errors and log them.
+- Ensure error handling is correct, using test suite with error injection.
+
+## Error Injection
+
+- Use the Apache Celix error_injector libraries to inject errors in unit tests in a controlled way.
+- Create a separate test suite for error injection tests.
+- Reset error injection setup on the `TearDown` function or destructor of the test fixture.
+- If an - internal or external - function is missing error injection support, add it to the error_injector library.
+ - Try to create small error injector libraries for specific functionality.
Review Comment:
For error injectors of optional external requirement, we need add `celix_subproject` to make them optional, see `ERROR_INJECTOR_MDNSRESPONDER` for an example.
For error injectors of optional internal subproject, we need to put it under the protection of subproject's switch. Currently we have no examples in Celix, but I do this in my own projects.
The above may be too detailed to be put in this document.
##########
documents/development/README.md:
##########
@@ -0,0 +1,539 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
+- Add a `static constexpr const char * const VERSION` to the service class, for the service version.
+
+### C++ Bundles
+
+- Use `CamelCase` for C++ bundle target names.
+- Do _not_ use a `Celix` prefix for C++ bundle target names.
+- Use `celix::` prefixed aliases for C++ bundle targets.
+- Use `CamelCase` for C++ bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C++ bundle targets.
+- Use `Apache_Celix_` prefix for C++ bundle symbolic names.
+- Use `Apache Celix ` prefix for C++ bundle names.
+- Use a `celix_` prefix for C++ bundle filenames.
+- Use a group name starting with `celix/` for C++ bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(MyBundle
+ SOURCES src/MyBundle.cc
+ SYMBOLIC_NAME "Apache_Celix_MyBundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_MyBundle"
+ VERSION "1.0.0"
+ GROUP "celix/MyBundleGroup"
+)
+add_library(celix::MyBundle ALIAS MyBundle)
+```
+
+### Unit Tests Naming
+
+- The test fixture should have a`TestSuite` postfix.
+- The source file should be named after the test fixture name and use a `.cc` extension.
+- Testcase names should use `CamelCase` (starting with a capital) and have a `Test` postfix.
+- When using error injection (one of the `error_injector` libraries) a separate test suite should be used.
+ - A `ErrorInjectionTestSuite` postfix should be used for the test fixture.
+ - The error injection setup should be reset on the `TearDown` function or destructor of the test fixture.
+
+## Comments and Documentation
+
+- Use Doxygen for code documentation.
+- Write comments that explain the purpose of the code, focusing on the "why" rather than the "how".
+- Apply doxygen documentation to all public API's.
+- Use the javadoc style for doxygen documentation.
+- Use `@` instead of `\` for doxygen commands.
+- Start with a `@brief` command and a short description.
+- For `@param` commands also provide in, out, or in/out information.
+
+## Formatting and Indentation
+
+- Use spaces for indentation and use 4 spaces per indentation level.
+- Keep line lengths under 120 characters, if possible, to enhance readability.
+- Place opening braces on the same line as the control statement or function definition,
+ and closing braces on a new line aligned with the control statement or function definition.
+- Use a single space before and after operators and around assignment statements.
+- Add a space after control keywords (`if`, `for`, `while`, etc.) that are followed by a parenthesis.
+- Always use braces ({ }) for control structures, even for single-statement blocks, to prevent errors.
+- Add a space after control keywords (`else`, `do`, etc) that are followed by a brace.
+- Do not add a space after the function name and the opening parenthesis.
+- For new files apply clang-format using the project .clang-format file.
+ - Note that this can be done using a plugin for your IDE or by running `clang-format -i <file>`.
+
+## Control Structures
+
+- Use `if`, `else if`, and `else` statements to handle multiple conditions.
+- Use `switch` statements for multiple conditions with a default case.
+- Use `while` statements for loops that may not execute.
+- Use `do`/`while` statements for loops that must execute at least once.
+- Use `for` statements for loops with a known number of iterations.
+- The use of `goto` is not allowed, except for error handling.
+- For C, try to prevent deeply nested control structures and prefer early returns or error handling `goto` statements.
+ - To prevent deeply nested control structures, the `CELIX_DO_IF` and `CELIX_GOTO_IF_ERR` macros can also be used.
+
+## Functions and Methods
+
+- Limit functions to a single responsibility or purpose, following the Single Responsibility Principle (SRP).
+- Keep functions short and focused, aiming for a length of fewer than 50 lines.
+- Ensure const correctness.
+- For C functions with a lot of different parameters, consider using an options struct.
+ - An options struct combined with a EMPTY_OPTIONS macro can be used to provide default values and a such
+ options struct can be updated backwards compatible.
+ - An options struct ensure that a lot of parameters can be configured, but also direct set on creation.
+- For C++ functions with a lot of different parameters, consider using a builder pattern.
+ - A builder pattern can be updated backwards compatible.
+ - A builder pattern ensure that a lot of parameters can be configured, but also direct set on construction.
+
+## Error Handling and Logging
+
+- For C++, throw an exception when an error occurs.
+- For C, if memory allocation is needed or another error can occur, ensure that a function returns a value
+ than can be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- Use consistent error handling techniques, such as returning error codes or using designated error handling functions.
+- Log errors, warnings, and other important events using the Apache Celix log helper functions or - for libraries -
+ the `celix_err` (TBD) functionality.
+- Always check for errors and log them.
+- Ensure error handling is correct, using test suite with error injection.
+
+## Error Injection
+
+- Use the Apache Celix error_injector libraries to inject errors in unit tests in a controlled way.
+- Create a separate test suite for error injection tests.
Review Comment:
Place them under the protection of if(LINKER_WRAP_SUPPORTED) so that these test suites could be turned off without LINKER_WRAP_SUPPORTED.
##########
documents/development/README.md:
##########
@@ -0,0 +1,539 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
+- Add a `static constexpr const char * const VERSION` to the service class, for the service version.
+
+### C++ Bundles
+
+- Use `CamelCase` for C++ bundle target names.
+- Do _not_ use a `Celix` prefix for C++ bundle target names.
+- Use `celix::` prefixed aliases for C++ bundle targets.
+- Use `CamelCase` for C++ bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C++ bundle targets.
+- Use `Apache_Celix_` prefix for C++ bundle symbolic names.
+- Use `Apache Celix ` prefix for C++ bundle names.
+- Use a `celix_` prefix for C++ bundle filenames.
+- Use a group name starting with `celix/` for C++ bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(MyBundle
+ SOURCES src/MyBundle.cc
+ SYMBOLIC_NAME "Apache_Celix_MyBundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_MyBundle"
+ VERSION "1.0.0"
+ GROUP "celix/MyBundleGroup"
+)
+add_library(celix::MyBundle ALIAS MyBundle)
+```
+
+### Unit Tests Naming
+
+- The test fixture should have a`TestSuite` postfix.
+- The source file should be named after the test fixture name and use a `.cc` extension.
+- Testcase names should use `CamelCase` (starting with a capital) and have a `Test` postfix.
+- When using error injection (one of the `error_injector` libraries) a separate test suite should be used.
+ - A `ErrorInjectionTestSuite` postfix should be used for the test fixture.
+ - The error injection setup should be reset on the `TearDown` function or destructor of the test fixture.
+
+## Comments and Documentation
+
+- Use Doxygen for code documentation.
+- Write comments that explain the purpose of the code, focusing on the "why" rather than the "how".
+- Apply doxygen documentation to all public API's.
+- Use the javadoc style for doxygen documentation.
+- Use `@` instead of `\` for doxygen commands.
+- Start with a `@brief` command and a short description.
+- For `@param` commands also provide in, out, or in/out information.
+
+## Formatting and Indentation
+
+- Use spaces for indentation and use 4 spaces per indentation level.
+- Keep line lengths under 120 characters, if possible, to enhance readability.
+- Place opening braces on the same line as the control statement or function definition,
+ and closing braces on a new line aligned with the control statement or function definition.
+- Use a single space before and after operators and around assignment statements.
+- Add a space after control keywords (`if`, `for`, `while`, etc.) that are followed by a parenthesis.
+- Always use braces ({ }) for control structures, even for single-statement blocks, to prevent errors.
+- Add a space after control keywords (`else`, `do`, etc) that are followed by a brace.
+- Do not add a space after the function name and the opening parenthesis.
+- For new files apply clang-format using the project .clang-format file.
+ - Note that this can be done using a plugin for your IDE or by running `clang-format -i <file>`.
+
+## Control Structures
+
+- Use `if`, `else if`, and `else` statements to handle multiple conditions.
+- Use `switch` statements for multiple conditions with a default case.
+- Use `while` statements for loops that may not execute.
+- Use `do`/`while` statements for loops that must execute at least once.
+- Use `for` statements for loops with a known number of iterations.
+- The use of `goto` is not allowed, except for error handling.
+- For C, try to prevent deeply nested control structures and prefer early returns or error handling `goto` statements.
+ - To prevent deeply nested control structures, the `CELIX_DO_IF` and `CELIX_GOTO_IF_ERR` macros can also be used.
+
+## Functions and Methods
+
+- Limit functions to a single responsibility or purpose, following the Single Responsibility Principle (SRP).
+- Keep functions short and focused, aiming for a length of fewer than 50 lines.
+- Ensure const correctness.
+- For C functions with a lot of different parameters, consider using an options struct.
+ - An options struct combined with a EMPTY_OPTIONS macro can be used to provide default values and a such
+ options struct can be updated backwards compatible.
+ - An options struct ensure that a lot of parameters can be configured, but also direct set on creation.
+- For C++ functions with a lot of different parameters, consider using a builder pattern.
+ - A builder pattern can be updated backwards compatible.
+ - A builder pattern ensure that a lot of parameters can be configured, but also direct set on construction.
+
+## Error Handling and Logging
+
+- For C++, throw an exception when an error occurs.
+- For C, if memory allocation is needed or another error can occur, ensure that a function returns a value
+ than can be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- Use consistent error handling techniques, such as returning error codes or using designated error handling functions.
+- Log errors, warnings, and other important events using the Apache Celix log helper functions or - for libraries -
+ the `celix_err` (TBD) functionality.
+- Always check for errors and log them.
+- Ensure error handling is correct, using test suite with error injection.
+
+## Error Injection
+
+- Use the Apache Celix error_injector libraries to inject errors in unit tests in a controlled way.
+- Create a separate test suite for error injection tests.
+- Reset error injection setup on the `TearDown` function or destructor of the test fixture.
+- If an - internal or external - function is missing error injection support, add it to the error_injector library.
+ - Try to create small error injector libraries for specific functionality.
+
+## Unit Test Approach
+
+- Use the Google Test framework for unit tests.
+- Use the Google Mock framework for mocking.
+- Use the Apache Celix error_injector libraries to inject errors in unit tests in a controlled way.
+- Test bundles by installing them in a programmatically created framework.
+- Test bundles by using their provided services and used services.
+- In most cases, libraries can be tested using a white box approach and bundles can be tested using a black box approach.
+- For libraries that are tested with the Apache Celix error_injector libraries or require access to private/hidden
+ functions, a separate "code under test" static library should be created.
+ This library should not hide its symbols and should have a `_cut` postfix.
+
+
+```cmake
+set(MY_LIB_SOURCES ...)
+set(MY_LIB_PUBLIC_LIBS ...)
+set(MY_LIB_PRIVATE_LIBS ...)
+add_library(my_lib SHARED ${MY_LIB_SOURCES})
+target_link_libraries(my_lib PUBLIC ${MY_LIB_PUBLIC_LIBS} PRIVATE ${MY_LIB_PRIVATE_LIBS})
+celix_target_hide_symbols(my_lib)
+...
+
+if (ENABLE_TESTING)
+ add_library(my_lib_cut STATIC ${MY_LIB_SOURCES})
+ target_link_libraries(my_lib PUBLIC ${MY_LIB_PUBLIC_LIBS} PRIVATE ${MY_LIB_PRIVATE_LIBS})
+ target_include_directories(my_lib PUBLIC
+ ${CMAKE_CURRENT_LIST_DIR}/src
+ ${CMAKE_CURRENT_LIST_DIR}/include
+ ${CMAKE_BINARY_DIR}/celix/gen/includes/my_lib
+ )
+endif ()
+```
+
+## Supported C and C++ Standards
+
+- C libraries should support C99. (TBD or C11))
+- C++ libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Unit test code can be written in C++17.
+
+## Library target properties
+
+For C and C++ shared libraries, the following target properties should be set:
+ - `VERSION` should be set to the library version.
+ - `SOVERSION` should be set to the library major version.
+ - `OUTPUT_NAME` should be set to the library name and should contain a `celix_` prefix.
+
+```cmake
+add_library(my_lib SHARED
+ src/my_lib.c)
+set_target_properties(my_lib
+ PROPERTIES
+ VERSION 1.0.0
+ SOVERSION 1
+ OUTPUT_NAME celix_my_lib)
+```
+
+For C and C++ static libraries, the following target properties should be set:
+ - `POSITION_INDEPENDENT_CODE` should be set to `ON` for static libraries.
+ - `OUTPUT_NAME` should be set to the library name and should contain a `celix_` prefix.
+
+```cmake
+add_library(my_lib STATIC
+ src/my_lib.c)
+set_target_properties(my_lib
+ PROPERTIES
+ POSITION_INDEPENDENT_CODE ON
+ OUTPUT_NAME celix_my_lib)
+```
+
+## Symbol Visibility
+
+- Header-only (INTERFACE) libraries should not configure symbol visibility.
+- Shared and static libraries should configure symbol visibility.
+ - Static library meant to be linked as PRIVATE should hide symbols.
+- Bundles should configure symbol visibility (this is done by default).
+
+### Configuring Symbol Visibility for C/C++ Libraries
+
+For Apache Celix shared libraries, symbol visibility should be configured using the CMake target
+properties `C_VISIBILITY_PRESET`, `CXX_VISIBILITY_PRESET` and `VISIBILITY_INLINES_HIDDEN` and a generated export
+header.
+
+The `C_VISIBILITY_PRESET` and `CXX_VISIBILITY_PRESET` target properties can be used to configure the default visibility
+of symbols in C and C++ code. The `VISIBILITY_INLINES_HIDDEN` property can be used to configure the visibility of
+inline functions. The `VISIBILITY_INLINES_HIDDEN` property is only supported for C++ code.
+
+The default visibility should be configured to hidden and symbols should be explicitly exported using the export
+marcos from a generated export header. The export header can be generated using the CMake function
+`generate_export_header`. Every library should have its own export header.
+
+For shared libraries, this can be done using the following CMake code:
+
+```cmake
+add_library(my_lib SHARED
+ src/my_lib.c)
+set_target_properties(my_lib PROPERTIES
+ C_VISIBILITY_PRESET hidden
+ #For C++ shared libraries also configure CXX_VISIBILITY_PRESET
+ CXX_VISIBILITY_PRESET hidden
+ VISIBILITY_INLINES_HIDDEN ON
+ OUTPUT_NAME celix_my_lib)
+target_include_directories(my_lib
+ PUBLIC
+ $<BUILD_INTERFACE:${CMAKE_BINARY_DIR}/celix/gen/includes/my_lib>
+ $<INSTALL_INTERFACE:include/celix_my_lib>
+ PRIVATE
+ src)
+
+#generate export header
+generate_export_header(my_lib
+ BASE_NAME "CELIX_MY_LIB"
+ EXPORT_FILE_NAME "${CMAKE_BINARY_DIR}/celix/gen/includes/my_lib/celix_my_lib_export.h")
+
+#install
+install(TARGETS my_lib EXPORT celix LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+ INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/celix_my_lib)
+install(DIRECTORY include/
+ DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/celix_my_lib)
+install(DIRECTORY ${CMAKE_BINARY_DIR}/celix/gen/includes/my_lib/
+ DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/celix_my_lib)
+```
+
+### Configuring Symbol Visibility for C/C++ Bundles
+
+For bundle, symbol visibility will default be configured to hidden. This can be default by providing
+the `DO_NOT_CONFIGURE_SYMBOL_VISIBILITY` option to the CMake `add_celix_bundle` function.
+
+If symbol visibility is not configured in the `add_celix_bundle`, symbol visibility should be configured the same
+way as a shared library.
+
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+ HIDE_SYMBOLS
Review Comment:
```suggestion
```
I guess `HIDE_SYMBOLS` is not needed any more, is it?
##########
documents/development/README.md:
##########
@@ -0,0 +1,539 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
+- Add a `static constexpr const char * const VERSION` to the service class, for the service version.
+
+### C++ Bundles
+
+- Use `CamelCase` for C++ bundle target names.
+- Do _not_ use a `Celix` prefix for C++ bundle target names.
+- Use `celix::` prefixed aliases for C++ bundle targets.
+- Use `CamelCase` for C++ bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C++ bundle targets.
+- Use `Apache_Celix_` prefix for C++ bundle symbolic names.
+- Use `Apache Celix ` prefix for C++ bundle names.
+- Use a `celix_` prefix for C++ bundle filenames.
+- Use a group name starting with `celix/` for C++ bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(MyBundle
+ SOURCES src/MyBundle.cc
+ SYMBOLIC_NAME "Apache_Celix_MyBundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_MyBundle"
+ VERSION "1.0.0"
+ GROUP "celix/MyBundleGroup"
+)
+add_library(celix::MyBundle ALIAS MyBundle)
+```
+
+### Unit Tests Naming
+
+- The test fixture should have a`TestSuite` postfix.
+- The source file should be named after the test fixture name and use a `.cc` extension.
+- Testcase names should use `CamelCase` (starting with a capital) and have a `Test` postfix.
+- When using error injection (one of the `error_injector` libraries) a separate test suite should be used.
+ - A `ErrorInjectionTestSuite` postfix should be used for the test fixture.
+ - The error injection setup should be reset on the `TearDown` function or destructor of the test fixture.
+
+## Comments and Documentation
+
+- Use Doxygen for code documentation.
+- Write comments that explain the purpose of the code, focusing on the "why" rather than the "how".
+- Apply doxygen documentation to all public API's.
+- Use the javadoc style for doxygen documentation.
+- Use `@` instead of `\` for doxygen commands.
+- Start with a `@brief` command and a short description.
+- For `@param` commands also provide in, out, or in/out information.
+
+## Formatting and Indentation
+
+- Use spaces for indentation and use 4 spaces per indentation level.
+- Keep line lengths under 120 characters, if possible, to enhance readability.
+- Place opening braces on the same line as the control statement or function definition,
+ and closing braces on a new line aligned with the control statement or function definition.
+- Use a single space before and after operators and around assignment statements.
+- Add a space after control keywords (`if`, `for`, `while`, etc.) that are followed by a parenthesis.
+- Always use braces ({ }) for control structures, even for single-statement blocks, to prevent errors.
+- Add a space after control keywords (`else`, `do`, etc) that are followed by a brace.
+- Do not add a space after the function name and the opening parenthesis.
+- For new files apply clang-format using the project .clang-format file.
+ - Note that this can be done using a plugin for your IDE or by running `clang-format -i <file>`.
+
+## Control Structures
+
+- Use `if`, `else if`, and `else` statements to handle multiple conditions.
+- Use `switch` statements for multiple conditions with a default case.
+- Use `while` statements for loops that may not execute.
+- Use `do`/`while` statements for loops that must execute at least once.
+- Use `for` statements for loops with a known number of iterations.
+- The use of `goto` is not allowed, except for error handling.
+- For C, try to prevent deeply nested control structures and prefer early returns or error handling `goto` statements.
+ - To prevent deeply nested control structures, the `CELIX_DO_IF` and `CELIX_GOTO_IF_ERR` macros can also be used.
+
+## Functions and Methods
+
+- Limit functions to a single responsibility or purpose, following the Single Responsibility Principle (SRP).
+- Keep functions short and focused, aiming for a length of fewer than 50 lines.
+- Ensure const correctness.
+- For C functions with a lot of different parameters, consider using an options struct.
+ - An options struct combined with a EMPTY_OPTIONS macro can be used to provide default values and a such
+ options struct can be updated backwards compatible.
+ - An options struct ensure that a lot of parameters can be configured, but also direct set on creation.
+- For C++ functions with a lot of different parameters, consider using a builder pattern.
+ - A builder pattern can be updated backwards compatible.
+ - A builder pattern ensure that a lot of parameters can be configured, but also direct set on construction.
+
+## Error Handling and Logging
+
+- For C++, throw an exception when an error occurs.
+- For C, if memory allocation is needed or another error can occur, ensure that a function returns a value
+ than can be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- Use consistent error handling techniques, such as returning error codes or using designated error handling functions.
+- Log errors, warnings, and other important events using the Apache Celix log helper functions or - for libraries -
+ the `celix_err` (TBD) functionality.
+- Always check for errors and log them.
+- Ensure error handling is correct, using test suite with error injection.
+
+## Error Injection
+
+- Use the Apache Celix error_injector libraries to inject errors in unit tests in a controlled way.
+- Create a separate test suite for error injection tests.
+- Reset error injection setup on the `TearDown` function or destructor of the test fixture.
+- If an - internal or external - function is missing error injection support, add it to the error_injector library.
+ - Try to create small error injector libraries for specific functionality.
+
+## Unit Test Approach
+
+- Use the Google Test framework for unit tests.
+- Use the Google Mock framework for mocking.
+- Use the Apache Celix error_injector libraries to inject errors in unit tests in a controlled way.
+- Test bundles by installing them in a programmatically created framework.
+- Test bundles by using their provided services and used services.
+- In most cases, libraries can be tested using a white box approach and bundles can be tested using a black box approach.
+- For libraries that are tested with the Apache Celix error_injector libraries or require access to private/hidden
+ functions, a separate "code under test" static library should be created.
+ This library should not hide its symbols and should have a `_cut` postfix.
+
+
+```cmake
+set(MY_LIB_SOURCES ...)
+set(MY_LIB_PUBLIC_LIBS ...)
+set(MY_LIB_PRIVATE_LIBS ...)
+add_library(my_lib SHARED ${MY_LIB_SOURCES})
+target_link_libraries(my_lib PUBLIC ${MY_LIB_PUBLIC_LIBS} PRIVATE ${MY_LIB_PRIVATE_LIBS})
+celix_target_hide_symbols(my_lib)
+...
+
+if (ENABLE_TESTING)
+ add_library(my_lib_cut STATIC ${MY_LIB_SOURCES})
+ target_link_libraries(my_lib PUBLIC ${MY_LIB_PUBLIC_LIBS} PRIVATE ${MY_LIB_PRIVATE_LIBS})
+ target_include_directories(my_lib PUBLIC
Review Comment:
```suggestion
target_include_directories(my_lib_cut PUBLIC
```
##########
documents/development/README.md:
##########
@@ -0,0 +1,539 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
+- Add a `static constexpr const char * const VERSION` to the service class, for the service version.
+
+### C++ Bundles
+
+- Use `CamelCase` for C++ bundle target names.
+- Do _not_ use a `Celix` prefix for C++ bundle target names.
+- Use `celix::` prefixed aliases for C++ bundle targets.
+- Use `CamelCase` for C++ bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C++ bundle targets.
+- Use `Apache_Celix_` prefix for C++ bundle symbolic names.
+- Use `Apache Celix ` prefix for C++ bundle names.
+- Use a `celix_` prefix for C++ bundle filenames.
+- Use a group name starting with `celix/` for C++ bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(MyBundle
+ SOURCES src/MyBundle.cc
+ SYMBOLIC_NAME "Apache_Celix_MyBundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_MyBundle"
+ VERSION "1.0.0"
+ GROUP "celix/MyBundleGroup"
+)
+add_library(celix::MyBundle ALIAS MyBundle)
+```
+
+### Unit Tests Naming
+
+- The test fixture should have a`TestSuite` postfix.
+- The source file should be named after the test fixture name and use a `.cc` extension.
+- Testcase names should use `CamelCase` (starting with a capital) and have a `Test` postfix.
+- When using error injection (one of the `error_injector` libraries) a separate test suite should be used.
+ - A `ErrorInjectionTestSuite` postfix should be used for the test fixture.
+ - The error injection setup should be reset on the `TearDown` function or destructor of the test fixture.
+
+## Comments and Documentation
+
+- Use Doxygen for code documentation.
+- Write comments that explain the purpose of the code, focusing on the "why" rather than the "how".
+- Apply doxygen documentation to all public API's.
+- Use the javadoc style for doxygen documentation.
+- Use `@` instead of `\` for doxygen commands.
+- Start with a `@brief` command and a short description.
+- For `@param` commands also provide in, out, or in/out information.
+
+## Formatting and Indentation
+
+- Use spaces for indentation and use 4 spaces per indentation level.
+- Keep line lengths under 120 characters, if possible, to enhance readability.
+- Place opening braces on the same line as the control statement or function definition,
+ and closing braces on a new line aligned with the control statement or function definition.
+- Use a single space before and after operators and around assignment statements.
+- Add a space after control keywords (`if`, `for`, `while`, etc.) that are followed by a parenthesis.
+- Always use braces ({ }) for control structures, even for single-statement blocks, to prevent errors.
+- Add a space after control keywords (`else`, `do`, etc) that are followed by a brace.
+- Do not add a space after the function name and the opening parenthesis.
+- For new files apply clang-format using the project .clang-format file.
+ - Note that this can be done using a plugin for your IDE or by running `clang-format -i <file>`.
+
+## Control Structures
+
+- Use `if`, `else if`, and `else` statements to handle multiple conditions.
+- Use `switch` statements for multiple conditions with a default case.
+- Use `while` statements for loops that may not execute.
+- Use `do`/`while` statements for loops that must execute at least once.
+- Use `for` statements for loops with a known number of iterations.
+- The use of `goto` is not allowed, except for error handling.
+- For C, try to prevent deeply nested control structures and prefer early returns or error handling `goto` statements.
+ - To prevent deeply nested control structures, the `CELIX_DO_IF` and `CELIX_GOTO_IF_ERR` macros can also be used.
+
+## Functions and Methods
+
+- Limit functions to a single responsibility or purpose, following the Single Responsibility Principle (SRP).
+- Keep functions short and focused, aiming for a length of fewer than 50 lines.
+- Ensure const correctness.
+- For C functions with a lot of different parameters, consider using an options struct.
+ - An options struct combined with a EMPTY_OPTIONS macro can be used to provide default values and a such
+ options struct can be updated backwards compatible.
+ - An options struct ensure that a lot of parameters can be configured, but also direct set on creation.
+- For C++ functions with a lot of different parameters, consider using a builder pattern.
+ - A builder pattern can be updated backwards compatible.
+ - A builder pattern ensure that a lot of parameters can be configured, but also direct set on construction.
+
+## Error Handling and Logging
+
+- For C++, throw an exception when an error occurs.
+- For C, if memory allocation is needed or another error can occur, ensure that a function returns a value
+ than can be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- Use consistent error handling techniques, such as returning error codes or using designated error handling functions.
+- Log errors, warnings, and other important events using the Apache Celix log helper functions or - for libraries -
+ the `celix_err` (TBD) functionality.
+- Always check for errors and log them.
+- Ensure error handling is correct, using test suite with error injection.
+
+## Error Injection
+
+- Use the Apache Celix error_injector libraries to inject errors in unit tests in a controlled way.
+- Create a separate test suite for error injection tests.
+- Reset error injection setup on the `TearDown` function or destructor of the test fixture.
+- If an - internal or external - function is missing error injection support, add it to the error_injector library.
+ - Try to create small error injector libraries for specific functionality.
+
+## Unit Test Approach
+
+- Use the Google Test framework for unit tests.
+- Use the Google Mock framework for mocking.
+- Use the Apache Celix error_injector libraries to inject errors in unit tests in a controlled way.
+- Test bundles by installing them in a programmatically created framework.
+- Test bundles by using their provided services and used services.
+- In most cases, libraries can be tested using a white box approach and bundles can be tested using a black box approach.
+- For libraries that are tested with the Apache Celix error_injector libraries or require access to private/hidden
+ functions, a separate "code under test" static library should be created.
+ This library should not hide its symbols and should have a `_cut` postfix.
+
+
+```cmake
+set(MY_LIB_SOURCES ...)
+set(MY_LIB_PUBLIC_LIBS ...)
+set(MY_LIB_PRIVATE_LIBS ...)
+add_library(my_lib SHARED ${MY_LIB_SOURCES})
+target_link_libraries(my_lib PUBLIC ${MY_LIB_PUBLIC_LIBS} PRIVATE ${MY_LIB_PRIVATE_LIBS})
+celix_target_hide_symbols(my_lib)
+...
+
+if (ENABLE_TESTING)
+ add_library(my_lib_cut STATIC ${MY_LIB_SOURCES})
+ target_link_libraries(my_lib PUBLIC ${MY_LIB_PUBLIC_LIBS} PRIVATE ${MY_LIB_PRIVATE_LIBS})
+ target_include_directories(my_lib PUBLIC
+ ${CMAKE_CURRENT_LIST_DIR}/src
+ ${CMAKE_CURRENT_LIST_DIR}/include
+ ${CMAKE_BINARY_DIR}/celix/gen/includes/my_lib
+ )
+endif ()
+```
+
+## Supported C and C++ Standards
+
+- C libraries should support C99. (TBD or C11))
Review Comment:
C99 is a good choice. Note that Linux has been upgraded to C99 last year. Toolchains used in embedded linux industry (provided by SoC vendors) are unbelievably outdated.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "PengZheng (via GitHub)" <gi...@apache.org>.
PengZheng commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1188043963
##########
documents/development/README.md:
##########
@@ -0,0 +1,539 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
+- Add a `static constexpr const char * const VERSION` to the service class, for the service version.
+
+### C++ Bundles
+
+- Use `CamelCase` for C++ bundle target names.
+- Do _not_ use a `Celix` prefix for C++ bundle target names.
+- Use `celix::` prefixed aliases for C++ bundle targets.
+- Use `CamelCase` for C++ bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C++ bundle targets.
+- Use `Apache_Celix_` prefix for C++ bundle symbolic names.
+- Use `Apache Celix ` prefix for C++ bundle names.
+- Use a `celix_` prefix for C++ bundle filenames.
+- Use a group name starting with `celix/` for C++ bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(MyBundle
+ SOURCES src/MyBundle.cc
+ SYMBOLIC_NAME "Apache_Celix_MyBundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_MyBundle"
+ VERSION "1.0.0"
+ GROUP "celix/MyBundleGroup"
+)
+add_library(celix::MyBundle ALIAS MyBundle)
+```
+
+### Unit Tests Naming
+
+- The test fixture should have a`TestSuite` postfix.
+- The source file should be named after the test fixture name and use a `.cc` extension.
+- Testcase names should use `CamelCase` (starting with a capital) and have a `Test` postfix.
+- When using error injection (one of the `error_injector` libraries) a separate test suite should be used.
+ - A `ErrorInjectionTestSuite` postfix should be used for the test fixture.
+ - The error injection setup should be reset on the `TearDown` function or destructor of the test fixture.
+
+## Comments and Documentation
+
+- Use Doxygen for code documentation.
+- Write comments that explain the purpose of the code, focusing on the "why" rather than the "how".
+- Apply doxygen documentation to all public API's.
+- Use the javadoc style for doxygen documentation.
+- Use `@` instead of `\` for doxygen commands.
+- Start with a `@brief` command and a short description.
+- For `@param` commands also provide in, out, or in/out information.
Review Comment:
And its `ERRORS` section, which I think is especially useful.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "PengZheng (via GitHub)" <gi...@apache.org>.
PengZheng commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1191871474
##########
documents/development/README.md:
##########
@@ -0,0 +1,537 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
Review Comment:
I think the former item refers to two specific library, i.e. Celix::framework and Celix::utils, while the latter item refers to other libraries.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "pnoltes (via GitHub)" <gi...@apache.org>.
pnoltes commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1195581624
##########
documents/development/README.md:
##########
@@ -0,0 +1,539 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
+- Add a `static constexpr const char * const VERSION` to the service class, for the service version.
+
+### C++ Bundles
+
+- Use `CamelCase` for C++ bundle target names.
+- Do _not_ use a `Celix` prefix for C++ bundle target names.
+- Use `celix::` prefixed aliases for C++ bundle targets.
+- Use `CamelCase` for C++ bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C++ bundle targets.
+- Use `Apache_Celix_` prefix for C++ bundle symbolic names.
+- Use `Apache Celix ` prefix for C++ bundle names.
+- Use a `celix_` prefix for C++ bundle filenames.
+- Use a group name starting with `celix/` for C++ bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(MyBundle
+ SOURCES src/MyBundle.cc
+ SYMBOLIC_NAME "Apache_Celix_MyBundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_MyBundle"
+ VERSION "1.0.0"
+ GROUP "celix/MyBundleGroup"
+)
+add_library(celix::MyBundle ALIAS MyBundle)
+```
+
+### Unit Tests Naming
+
+- The test fixture should have a`TestSuite` postfix.
+- The source file should be named after the test fixture name and use a `.cc` extension.
+- Testcase names should use `CamelCase` (starting with a capital) and have a `Test` postfix.
+- When using error injection (one of the `error_injector` libraries) a separate test suite should be used.
+ - A `ErrorInjectionTestSuite` postfix should be used for the test fixture.
+ - The error injection setup should be reset on the `TearDown` function or destructor of the test fixture.
+
+## Comments and Documentation
+
+- Use Doxygen for code documentation.
+- Write comments that explain the purpose of the code, focusing on the "why" rather than the "how".
+- Apply doxygen documentation to all public API's.
+- Use the javadoc style for doxygen documentation.
+- Use `@` instead of `\` for doxygen commands.
+- Start with a `@brief` command and a short description.
+- For `@param` commands also provide in, out, or in/out information.
+
+## Formatting and Indentation
+
+- Use spaces for indentation and use 4 spaces per indentation level.
+- Keep line lengths under 120 characters, if possible, to enhance readability.
+- Place opening braces on the same line as the control statement or function definition,
+ and closing braces on a new line aligned with the control statement or function definition.
+- Use a single space before and after operators and around assignment statements.
+- Add a space after control keywords (`if`, `for`, `while`, etc.) that are followed by a parenthesis.
+- Always use braces ({ }) for control structures, even for single-statement blocks, to prevent errors.
+- Add a space after control keywords (`else`, `do`, etc) that are followed by a brace.
+- Do not add a space after the function name and the opening parenthesis.
+- For new files apply clang-format using the project .clang-format file.
+ - Note that this can be done using a plugin for your IDE or by running `clang-format -i <file>`.
+
+## Control Structures
+
+- Use `if`, `else if`, and `else` statements to handle multiple conditions.
+- Use `switch` statements for multiple conditions with a default case.
+- Use `while` statements for loops that may not execute.
+- Use `do`/`while` statements for loops that must execute at least once.
+- Use `for` statements for loops with a known number of iterations.
+- The use of `goto` is not allowed, except for error handling.
+- For C, try to prevent deeply nested control structures and prefer early returns or error handling `goto` statements.
+ - To prevent deeply nested control structures, the `CELIX_DO_IF` and `CELIX_GOTO_IF_ERR` macros can also be used.
+
+## Functions and Methods
+
+- Limit functions to a single responsibility or purpose, following the Single Responsibility Principle (SRP).
+- Keep functions short and focused, aiming for a length of fewer than 50 lines.
+- Ensure const correctness.
+- For C functions with a lot of different parameters, consider using an options struct.
+ - An options struct combined with a EMPTY_OPTIONS macro can be used to provide default values and a such
+ options struct can be updated backwards compatible.
+ - An options struct ensure that a lot of parameters can be configured, but also direct set on creation.
+- For C++ functions with a lot of different parameters, consider using a builder pattern.
+ - A builder pattern can be updated backwards compatible.
+ - A builder pattern ensure that a lot of parameters can be configured, but also direct set on construction.
+
+## Error Handling and Logging
+
+- For C++, throw an exception when an error occurs.
+- For C, if memory allocation is needed or another error can occur, ensure that a function returns a value
+ than can be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- Use consistent error handling techniques, such as returning error codes or using designated error handling functions.
+- Log errors, warnings, and other important events using the Apache Celix log helper functions or - for libraries -
+ the `celix_err` (TBD) functionality.
+- Always check for errors and log them.
+- Ensure error handling is correct, using test suite with error injection.
+
+## Error Injection
+
+- Use the Apache Celix error_injector libraries to inject errors in unit tests in a controlled way.
+- Create a separate test suite for error injection tests.
+- Reset error injection setup on the `TearDown` function or destructor of the test fixture.
+- If an - internal or external - function is missing error injection support, add it to the error_injector library.
+ - Try to create small error injector libraries for specific functionality.
Review Comment:
> For error injectors of optional external requirement, we need add `celix_subproject` to make them optional, see `ERROR_INJECTOR_MDNSRESPONDER` for an example.
>
> For error injectors of optional internal subproject, we need to put it under the protection of subproject's switch. Currently we have no examples in Celix, but I do this in my own projects.
>
> The above may be too detailed to be put in this document.
Is this really needed?
I think this can also be done by a find_package(OPTIONAL). So mdns responder example:
Instead of:
```
celix_subproject(ERROR_INJECTOR_MDNSRESPONDER "Option to enable building the mdnsresponder error injector" OFF)
if (ERROR_INJECTOR_MDNSRESPONDER)
add_subdirectory(mdnsresponder)
endif ()
```
maybe this:
```
find_package(DNSSD QUIET)
if (DNSSD_FOUND)
add_subdirectory(mdnsresponder)
endif ()
```
In latter example if the `RSA_DISCOVERY_ZEROCONF` subproject is enabled, the `find_package(DNSSD REQUIRED)` is called and as result the mdnsresponder error injection library should also automatically build (no extra config needed)
WDYT?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "pnoltes (via GitHub)" <gi...@apache.org>.
pnoltes commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1194937708
##########
documents/development/README.md:
##########
@@ -0,0 +1,537 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
Review Comment:
No not yet. Is there a good reason to do this?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "pnoltes (via GitHub)" <gi...@apache.org>.
pnoltes commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1187704183
##########
documents/development/README.md:
##########
@@ -0,0 +1,539 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
+- Add a `static constexpr const char * const VERSION` to the service class, for the service version.
+
+### C++ Bundles
+
+- Use `CamelCase` for C++ bundle target names.
+- Do _not_ use a `Celix` prefix for C++ bundle target names.
+- Use `celix::` prefixed aliases for C++ bundle targets.
+- Use `CamelCase` for C++ bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C++ bundle targets.
+- Use `Apache_Celix_` prefix for C++ bundle symbolic names.
+- Use `Apache Celix ` prefix for C++ bundle names.
+- Use a `celix_` prefix for C++ bundle filenames.
+- Use a group name starting with `celix/` for C++ bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(MyBundle
+ SOURCES src/MyBundle.cc
+ SYMBOLIC_NAME "Apache_Celix_MyBundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_MyBundle"
+ VERSION "1.0.0"
+ GROUP "celix/MyBundleGroup"
+)
+add_library(celix::MyBundle ALIAS MyBundle)
+```
+
+### Unit Tests Naming
+
+- The test fixture should have a`TestSuite` postfix.
+- The source file should be named after the test fixture name and use a `.cc` extension.
+- Testcase names should use `CamelCase` (starting with a capital) and have a `Test` postfix.
+- When using error injection (one of the `error_injector` libraries) a separate test suite should be used.
+ - A `ErrorInjectionTestSuite` postfix should be used for the test fixture.
+ - The error injection setup should be reset on the `TearDown` function or destructor of the test fixture.
+
+## Comments and Documentation
+
+- Use Doxygen for code documentation.
+- Write comments that explain the purpose of the code, focusing on the "why" rather than the "how".
+- Apply doxygen documentation to all public API's.
+- Use the javadoc style for doxygen documentation.
+- Use `@` instead of `\` for doxygen commands.
+- Start with a `@brief` command and a short description.
+- For `@param` commands also provide in, out, or in/out information.
Review Comment:
Good point, maybe some example of good doxygen usage should be included.
For `man 2 write` return documentation you mean to full paragraph:
> On success, the number of bytes written is returned. On error, -1 is returned, and errno is set to indicate the error.
> Note that a successful write() may transfer fewer than count bytes. Such partial writes can occur for various reasons; for example, because there was insufficient space on the disk device to write all of the requested bytes, or because a blocked write() to a socket, pipe, or similar was interrupted by a signal handler after it had transferred some, but before
it had transferred all of the requested bytes. In the event of a partial write, the caller can make another write() call to transfer the remaining bytes. The subsequent call will either transfer further bytes or may result in an error (e.g., if the disk is now full).
> If count is zero and fd refers to a regular file, then write() may return a failure status if one of the errors below is detected. If no errors are detected, or error detection is not performed, 0 is returned without causing any other effect. If count is zero and fd refers to a file other than a regular file, the results are not specified.
or just the first sentence?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "rlenferink (via GitHub)" <gi...@apache.org>.
rlenferink commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1191584251
##########
documents/development/README.md:
##########
@@ -0,0 +1,537 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
+- Add a `static constexpr const char * const VERSION` to the service class, for the service version.
+
+### C++ Bundles
+
+- Use `CamelCase` for C++ bundle target names.
+- Do _not_ use a `Celix` prefix for C++ bundle target names.
+- Use `celix::` prefixed aliases for C++ bundle targets.
+- Use `CamelCase` for C++ bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C++ bundle targets.
+- Use `Apache_Celix_` prefix for C++ bundle symbolic names.
+- Use `Apache Celix ` prefix for C++ bundle names.
+- Use a `celix_` prefix for C++ bundle filenames.
+- Use a group name starting with `celix/` for C++ bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(MyBundle
+ SOURCES src/MyBundle.cc
+ SYMBOLIC_NAME "Apache_Celix_MyBundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_MyBundle"
+ VERSION "1.0.0"
+ GROUP "celix/MyBundleGroup"
+)
+add_library(celix::MyBundle ALIAS MyBundle)
+```
+
+### Unit Tests Naming
+
+- The test fixture should have a`TestSuite` postfix.
+- The source file should be named after the test fixture name and use a `.cc` extension.
+- Testcase names should use `CamelCase` (starting with a capital) and have a `Test` postfix.
+- When using error injection (one of the `error_injector` libraries) a separate test suite should be used.
+ - A `ErrorInjectionTestSuite` postfix should be used for the test fixture.
+ - The error injection setup should be reset on the `TearDown` function or destructor of the test fixture.
+
+## Comments and Documentation
+
+- Use Doxygen for code documentation.
+- Write comments that explain the purpose of the code, focusing on the "why" rather than the "how".
+- Apply doxygen documentation to all public API's.
+- Use the javadoc style for doxygen documentation.
+- Use `@` instead of `\` for doxygen commands.
+- Start with a `@brief` command and a short description.
+- For `@param` commands also provide in, out, or in/out information.
+
+## Formatting and Indentation
+
+- Use spaces for indentation and use 4 spaces per indentation level.
+- Keep line lengths under 120 characters, if possible, to enhance readability.
+- Place opening braces on the same line as the control statement or function definition,
+ and closing braces on a new line aligned with the control statement or function definition.
+- Use a single space before and after operators and around assignment statements.
+- Add a space after control keywords (`if`, `for`, `while`, etc.) that are followed by a parenthesis.
+- Always use braces ({ }) for control structures, even for single-statement blocks, to prevent errors.
+- Add a space after control keywords (`else`, `do`, etc) that are followed by a brace.
+- Do not add a space after the function name and the opening parenthesis.
+- For new files apply clang-format using the project .clang-format file.
+ - Note that this can be done using a plugin for your IDE or by running `clang-format -i <file>`.
+
+## Control Structures
+
+- Use `if`, `else if`, and `else` statements to handle multiple conditions.
+- Use `switch` statements for multiple conditions with a default case.
+- Use `while` statements for loops that may not execute.
+- Use `do`/`while` statements for loops that must execute at least once.
+- Use `for` statements for loops with a known number of iterations.
+- The use of `goto` is not allowed, except for error handling.
+- For C, try to prevent deeply nested control structures and prefer early returns or error handling `goto` statements.
+ - To prevent deeply nested control structures, the `CELIX_DO_IF` and `CELIX_GOTO_IF_ERR` macros can also be used.
+
+## Functions and Methods
+
+- Limit functions to a single responsibility or purpose, following the Single Responsibility Principle (SRP).
+- Keep functions short and focused, aiming for a length of fewer than 50 lines.
+- Ensure const correctness.
+- For C functions with a lot of different parameters, consider using an options struct.
+ - An options struct combined with a EMPTY_OPTIONS macro can be used to provide default values and a such
+ options struct can be updated backwards compatible.
+ - An options struct ensure that a lot of parameters can be configured, but also direct set on creation.
+- For C++ functions with a lot of different parameters, consider using a builder pattern.
+ - A builder pattern can be updated backwards compatible.
+ - A builder pattern ensure that a lot of parameters can be configured, but also direct set on construction.
+
+## Error Handling and Logging
+
+- For C++, throw an exception when an error occurs.
+- For C, if memory allocation is needed or another error can occur, ensure that a function returns a value
+ than can be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- Use consistent error handling techniques, such as returning error codes or using designated error handling functions.
+- Log errors, warnings, and other important events using the Apache Celix log helper functions or - for libraries -
+ the `celix_err` (TBD) functionality.
+- Always check for errors and log them.
+- Ensure error handling is correct, using test suite with error injection.
+
+## Error Injection
+
+- Use the Apache Celix error_injector libraries to inject errors in unit tests in a controlled way.
+- Create a separate test suite for error injection tests.
+- Reset error injection setup on the `TearDown` function or destructor of the test fixture.
+- If an - internal or external - function is missing error injection support, add it to the error_injector library.
+ - Try to create small error injector libraries for specific functionality.
+
+## Unit Test Approach
+
+- Use the Google Test framework for unit tests.
+- Use the Google Mock framework for mocking.
+- Use the Apache Celix error_injector libraries to inject errors in unit tests in a controlled way.
+- Test bundles by installing them in a programmatically created framework.
+- Test bundles by using their provided services and used services.
+- In most cases, libraries can be tested using a white box approach and bundles can be tested using a black box approach.
+- For libraries that are tested with the Apache Celix error_injector libraries or require access to private/hidden
+ functions, a separate "code under test" static library should be created.
+ This library should not hide its symbols and should have a `_cut` postfix.
+
+
+```cmake
+set(MY_LIB_SOURCES ...)
+set(MY_LIB_PUBLIC_LIBS ...)
+set(MY_LIB_PRIVATE_LIBS ...)
+add_library(my_lib SHARED ${MY_LIB_SOURCES})
+target_link_libraries(my_lib PUBLIC ${MY_LIB_PUBLIC_LIBS} PRIVATE ${MY_LIB_PRIVATE_LIBS})
+celix_target_hide_symbols(my_lib)
+...
+
+if (ENABLE_TESTING)
+ add_library(my_lib_cut STATIC ${MY_LIB_SOURCES})
+ target_link_libraries(my_lib_cut PUBLIC ${MY_LIB_PUBLIC_LIBS} ${MY_LIB_PRIVATE_LIBS})
+ target_include_directories(my_lib_cut PUBLIC
+ ${CMAKE_CURRENT_LIST_DIR}/src
+ ${CMAKE_CURRENT_LIST_DIR}/include
+ ${CMAKE_BINARY_DIR}/celix/gen/includes/my_lib
+ )
+endif ()
+```
+
+## Supported C and C++ Standards
+
+- C libraries should support C99. (TBD or C11))
+- C++ libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Unit test code can be written in C++17.
+
+## Library target properties
+
+For C and C++ shared libraries, the following target properties should be set:
+ - `VERSION` should be set to the library version.
+ - `SOVERSION` should be set to the library major version.
+ - `OUTPUT_NAME` should be set to the library name and should contain a `celix_` prefix.
+
+```cmake
+add_library(my_lib SHARED
+ src/my_lib.c)
+set_target_properties(my_lib
+ PROPERTIES
+ VERSION 1.0.0
+ SOVERSION 1
+ OUTPUT_NAME celix_my_lib)
+```
+
+For C and C++ static libraries, the following target properties should be set:
+ - `POSITION_INDEPENDENT_CODE` should be set to `ON` for static libraries.
+ - `OUTPUT_NAME` should be set to the library name and should contain a `celix_` prefix.
+
+```cmake
+add_library(my_lib STATIC
+ src/my_lib.c)
+set_target_properties(my_lib
+ PROPERTIES
+ POSITION_INDEPENDENT_CODE ON
+ OUTPUT_NAME celix_my_lib)
+```
+
+## Symbol Visibility
+
+- Header-only (INTERFACE) libraries should not configure symbol visibility.
+- Shared and static libraries should configure symbol visibility.
+ - Static library meant to be linked as PRIVATE should hide symbols.
+- Bundles should configure symbol visibility (this is done by default).
+
+### Configuring Symbol Visibility for C/C++ Libraries
+
+For Apache Celix shared libraries, symbol visibility should be configured using the CMake target
+properties `C_VISIBILITY_PRESET`, `CXX_VISIBILITY_PRESET` and `VISIBILITY_INLINES_HIDDEN` and a generated export
+header.
+
+The `C_VISIBILITY_PRESET` and `CXX_VISIBILITY_PRESET` target properties can be used to configure the default visibility
+of symbols in C and C++ code. The `VISIBILITY_INLINES_HIDDEN` property can be used to configure the visibility of
+inline functions. The `VISIBILITY_INLINES_HIDDEN` property is only supported for C++ code.
+
+The default visibility should be configured to hidden and symbols should be explicitly exported using the export
+marcos from a generated export header. The export header can be generated using the CMake function
+`generate_export_header`. Every library should have its own export header.
+
+For shared libraries, this can be done using the following CMake code:
+
+```cmake
+add_library(my_lib SHARED
+ src/my_lib.c)
+set_target_properties(my_lib PROPERTIES
+ C_VISIBILITY_PRESET hidden
+ #For C++ shared libraries also configure CXX_VISIBILITY_PRESET
+ CXX_VISIBILITY_PRESET hidden
+ VISIBILITY_INLINES_HIDDEN ON
+ OUTPUT_NAME celix_my_lib)
+target_include_directories(my_lib
+ PUBLIC
+ $<BUILD_INTERFACE:${CMAKE_BINARY_DIR}/celix/gen/includes/my_lib>
+ PRIVATE
+ src)
+
+#generate export header
+generate_export_header(my_lib
+ BASE_NAME "CELIX_MY_LIB"
+ EXPORT_FILE_NAME "${CMAKE_BINARY_DIR}/celix/gen/includes/my_lib/celix_my_lib_export.h")
+
+#install
+install(TARGETS my_lib EXPORT celix LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+ INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/celix_my_lib)
+install(DIRECTORY include/
+ DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/celix_my_lib)
+install(DIRECTORY ${CMAKE_BINARY_DIR}/celix/gen/includes/my_lib/
+ DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/celix_my_lib)
+```
+
+### Configuring Symbol Visibility for C/C++ Bundles
+
+For bundle, symbol visibility will default be configured to hidden. This can be default by providing
+the `DO_NOT_CONFIGURE_SYMBOL_VISIBILITY` option to the CMake `add_celix_bundle` function.
+
+If symbol visibility is not configured in the `add_celix_bundle`, symbol visibility should be configured the same
+way as a shared library.
+
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+## Branch naming
+
+- Prefix feature branches with `feature/`, hotfix branches with `hotfix/`, bugfix branches with `bugfix/`
+ and release branches with `release/`.
+- If you are working on an issue, prefix the branch name with the issue number. E.g., `feature/1234-add-feature`.
+- Hotfix branches are for urgent fixes that need to be applied as soon as possible.
+- Use short and descriptive branch names.
+
+## Commit Messages
+
+- Utilize the imperative mood when writing commit messages (e.g., "Add feature" instead of "Adds feature"
+ or "Added feature"). This style aligns with git's auto-generated messages for merge commits or revert actions.
+- Ensure that commit messages are descriptive and provide meaningful context.
+- Keep the first line of the commit message concise, ideally under 50 characters.
+ This summary line serves as a quick overview of the change and should be easy to read in git logs.
+- If more context is needed, separate the summary line from the body with a blank line.
+ The body can provide additional details, explanations, or reasoning behind the changes.
+ Aim to keep each line of the commit message body wrapped at around 72 characters for optimal readability.
+- Use bullet points, numbered lists, or other formatting conventions when listing multiple changes or points in the
+ commit message body to improve readability.
+- When applicable, reference related issues, bug reports, or pull requests in the commit message body to
+ provide additional context and establish connections between the commit and the larger project.
+ - If your commit fixes, closes, or resolves an issue, use one of these keywords followed by the issue number
+ (e.g., "fixes #42", "closes #42", or "resolves #42").
+ - If you want to reference an issue without closing it, simply mention the issue number
+ (e.g., "related to #42" or "#42").
+
+## Benchmarking
+
+- When needed, use benchmarking to measure performance.
+- Use the Google Benchmark framework for benchmarking.
Review Comment:
Why only aim at using Google Benchmark? If someone finds a better tool to do the job, that's up to them IMO (up to the user).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "pnoltes (via GitHub)" <gi...@apache.org>.
pnoltes commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1195587649
##########
documents/development/README.md:
##########
@@ -0,0 +1,537 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
Review Comment:
I moved the two lines to `### C++ Libaries` and tried to clarify them a bit more.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "PengZheng (via GitHub)" <gi...@apache.org>.
PengZheng commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1195863302
##########
documents/development/README.md:
##########
@@ -0,0 +1,539 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
+- Add a `static constexpr const char * const VERSION` to the service class, for the service version.
+
+### C++ Bundles
+
+- Use `CamelCase` for C++ bundle target names.
+- Do _not_ use a `Celix` prefix for C++ bundle target names.
+- Use `celix::` prefixed aliases for C++ bundle targets.
+- Use `CamelCase` for C++ bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C++ bundle targets.
+- Use `Apache_Celix_` prefix for C++ bundle symbolic names.
+- Use `Apache Celix ` prefix for C++ bundle names.
+- Use a `celix_` prefix for C++ bundle filenames.
+- Use a group name starting with `celix/` for C++ bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(MyBundle
+ SOURCES src/MyBundle.cc
+ SYMBOLIC_NAME "Apache_Celix_MyBundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_MyBundle"
+ VERSION "1.0.0"
+ GROUP "celix/MyBundleGroup"
+)
+add_library(celix::MyBundle ALIAS MyBundle)
+```
+
+### Unit Tests Naming
+
+- The test fixture should have a`TestSuite` postfix.
+- The source file should be named after the test fixture name and use a `.cc` extension.
+- Testcase names should use `CamelCase` (starting with a capital) and have a `Test` postfix.
+- When using error injection (one of the `error_injector` libraries) a separate test suite should be used.
+ - A `ErrorInjectionTestSuite` postfix should be used for the test fixture.
+ - The error injection setup should be reset on the `TearDown` function or destructor of the test fixture.
+
+## Comments and Documentation
+
+- Use Doxygen for code documentation.
+- Write comments that explain the purpose of the code, focusing on the "why" rather than the "how".
+- Apply doxygen documentation to all public API's.
+- Use the javadoc style for doxygen documentation.
+- Use `@` instead of `\` for doxygen commands.
+- Start with a `@brief` command and a short description.
+- For `@param` commands also provide in, out, or in/out information.
+
+## Formatting and Indentation
+
+- Use spaces for indentation and use 4 spaces per indentation level.
+- Keep line lengths under 120 characters, if possible, to enhance readability.
+- Place opening braces on the same line as the control statement or function definition,
+ and closing braces on a new line aligned with the control statement or function definition.
+- Use a single space before and after operators and around assignment statements.
+- Add a space after control keywords (`if`, `for`, `while`, etc.) that are followed by a parenthesis.
+- Always use braces ({ }) for control structures, even for single-statement blocks, to prevent errors.
+- Add a space after control keywords (`else`, `do`, etc) that are followed by a brace.
+- Do not add a space after the function name and the opening parenthesis.
+- For new files apply clang-format using the project .clang-format file.
+ - Note that this can be done using a plugin for your IDE or by running `clang-format -i <file>`.
+
+## Control Structures
+
+- Use `if`, `else if`, and `else` statements to handle multiple conditions.
+- Use `switch` statements for multiple conditions with a default case.
+- Use `while` statements for loops that may not execute.
+- Use `do`/`while` statements for loops that must execute at least once.
+- Use `for` statements for loops with a known number of iterations.
+- The use of `goto` is not allowed, except for error handling.
+- For C, try to prevent deeply nested control structures and prefer early returns or error handling `goto` statements.
+ - To prevent deeply nested control structures, the `CELIX_DO_IF` and `CELIX_GOTO_IF_ERR` macros can also be used.
+
+## Functions and Methods
+
+- Limit functions to a single responsibility or purpose, following the Single Responsibility Principle (SRP).
+- Keep functions short and focused, aiming for a length of fewer than 50 lines.
+- Ensure const correctness.
+- For C functions with a lot of different parameters, consider using an options struct.
+ - An options struct combined with a EMPTY_OPTIONS macro can be used to provide default values and a such
+ options struct can be updated backwards compatible.
+ - An options struct ensure that a lot of parameters can be configured, but also direct set on creation.
+- For C++ functions with a lot of different parameters, consider using a builder pattern.
+ - A builder pattern can be updated backwards compatible.
+ - A builder pattern ensure that a lot of parameters can be configured, but also direct set on construction.
+
+## Error Handling and Logging
+
+- For C++, throw an exception when an error occurs.
+- For C, if memory allocation is needed or another error can occur, ensure that a function returns a value
+ than can be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- Use consistent error handling techniques, such as returning error codes or using designated error handling functions.
+- Log errors, warnings, and other important events using the Apache Celix log helper functions or - for libraries -
+ the `celix_err` (TBD) functionality.
+- Always check for errors and log them.
+- Ensure error handling is correct, using test suite with error injection.
+
+## Error Injection
+
+- Use the Apache Celix error_injector libraries to inject errors in unit tests in a controlled way.
+- Create a separate test suite for error injection tests.
+- Reset error injection setup on the `TearDown` function or destructor of the test fixture.
+- If an - internal or external - function is missing error injection support, add it to the error_injector library.
+ - Try to create small error injector libraries for specific functionality.
Review Comment:
Currently, we don't have automatic module dependency deduction within the same package, which I plan to add in a future PR. Note that we do have automatic module dependency deduction between conan packages, which conan gives us for free. Dependency deduction works by manipulating these CMake options in conanfile so that these mocks won't be built if not needed.
In that future PR, I also want to make our error injectors installable so that they can be reused by our downstream users.
For Celix's own optional module's mock, it can reuse the module's option.
For external library's mock, a separate subproject is needed.
I found that our error injectors is AI-friendly, and can be generated easily by generative-AI without any IP risks.
Large amounts of reusable error injectors will make our users very happy.
For now we don't need to mention anything about this in the coding convention.
When that future PR is worked out, we can revisit this topic.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "rlenferink (via GitHub)" <gi...@apache.org>.
rlenferink commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1193141531
##########
.clang-format:
##########
@@ -0,0 +1,27 @@
+BasedOnStyle: LLVM
Review Comment:
What is the additional benefit of the `Language: Cpp` here, since the GitHub statistics for this repo list that the celix repo contains 60% C code and 30% C++ code.
(I don't know how accurate those stats are)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "pnoltes (via GitHub)" <gi...@apache.org>.
pnoltes commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1200957080
##########
documents/development/README.md:
##########
@@ -0,0 +1,539 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
Review Comment:
I updated the clang-format and asterisk issue should be resolved.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "pnoltes (via GitHub)" <gi...@apache.org>.
pnoltes commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1200964643
##########
.clang-format:
##########
@@ -0,0 +1,27 @@
+BasedOnStyle: LLVM
+IndentWidth: 4
+AllowShortIfStatementsOnASingleLine: false
+AlwaysBreakTemplateDeclarations: Yes
+BinPackArguments: false
+BinPackParameters: false
+BreakBeforeBraces: Attach
+ColumnLimit: 120
+ConstructorInitializerIndentWidth: 4
+Cpp11BracedListStyle: true
+DerivePointerAlignment: false
+IncludeBlocks: Regroup
Review Comment:
clang-format does take into account. So when you run formatting over a `foo.c` source file and there is a include of `foo.h` this will be included first.
This should even be extendable with the `IncludeIsMainRegex` option, but I could not get that to work.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "WopsS (via GitHub)" <gi...@apache.org>.
WopsS commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1205768436
##########
.clang-format:
##########
@@ -0,0 +1,27 @@
+BasedOnStyle: LLVM
Review Comment:
As far as I know, it can be used for C.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "pnoltes (via GitHub)" <gi...@apache.org>.
pnoltes commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1216919292
##########
documents/development/README.md:
##########
@@ -0,0 +1,537 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
Review Comment:
Actual space depends of course on alignment, but if there are no real downsides to using a `std::int8_t`, I think this is a good idea. I will update this.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "rlenferink (via GitHub)" <gi...@apache.org>.
rlenferink commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1191564589
##########
documents/development/README.md:
##########
@@ -0,0 +1,537 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
Review Comment:
What do we do when switching to newer C++ versions? Update the coding guidelines? Do we need to mention the C++ version in the coding guidelines? Is that not more of a technical 'setting'?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "rlenferink (via GitHub)" <gi...@apache.org>.
rlenferink commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1191563275
##########
documents/development/README.md:
##########
@@ -0,0 +1,537 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
Review Comment:
Don't this and the line above it contradict each other?
First sentence: `For the Apache Celix framework and utils lib only` => I read this as "header-only C++ files are only allowed for the Apache Celix framework and utils lib"
`Prefer header-only C++ files for the Apache Celix libraries` => I read this as "header-only C++ files are preferred for all Apache Celix libraries".
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "rlenferink (via GitHub)" <gi...@apache.org>.
rlenferink commented on PR #544:
URL: https://github.com/apache/celix/pull/544#issuecomment-1544536573
/cc @WopsS maybe you will find this an interesting PR as well ;)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "WopsS (via GitHub)" <gi...@apache.org>.
WopsS commented on PR #544:
URL: https://github.com/apache/celix/pull/544#issuecomment-1546111509
Good job for writing all of these!
Since some things can be overseen in reviews I suggest to setup a workflow to check the formatting of new C++ code. If this is a good idea I can submit a PR for it.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "PengZheng (via GitHub)" <gi...@apache.org>.
PengZheng commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1191871474
##########
documents/development/README.md:
##########
@@ -0,0 +1,537 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
Review Comment:
I think the former item refers to `Celix::framework` and `Celix::utils`, while the latter item refers to other libraries.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "PengZheng (via GitHub)" <gi...@apache.org>.
PengZheng commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1195869466
##########
.clang-format:
##########
@@ -0,0 +1,27 @@
+BasedOnStyle: LLVM
+IndentWidth: 4
+AllowShortIfStatementsOnASingleLine: false
+AlwaysBreakTemplateDeclarations: Yes
+BinPackArguments: false
+BinPackParameters: false
+BreakBeforeBraces: Attach
+ColumnLimit: 120
+ConstructorInitializerIndentWidth: 4
+Cpp11BracedListStyle: true
+DerivePointerAlignment: false
+IncludeBlocks: Regroup
Review Comment:
AFAIK, there is a case where manually organizing headers can be useful: for each .h/.c pairs, e.g., celix_bundle_cache.h(.c), always include the header file (`celix_bundle_cache.h`) in the first line of the non-comment part of the source file (`celix_bundle_cache.c`) to make sure the header file is self-contained, which means it can be used alone. Self-contained header file is really nice.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "pnoltes (via GitHub)" <gi...@apache.org>.
pnoltes commented on PR #544:
URL: https://github.com/apache/celix/pull/544#issuecomment-1549392565
> Good job
Thanks.
Yes I think that is a good idea, ideally this only applies for adjusted code and new source files but I would be interested in workflow that can help us with ensuring consistent formatting.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "pnoltes (via GitHub)" <gi...@apache.org>.
pnoltes commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1194942863
##########
.clang-format:
##########
@@ -0,0 +1,27 @@
+BasedOnStyle: LLVM
Review Comment:
As far as I know clang-format support Cpp as language, but not C. Also Celix is a mix of C and C++ (mainly C)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "pnoltes (via GitHub)" <gi...@apache.org>.
pnoltes commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1195583553
##########
documents/development/README.md:
##########
@@ -0,0 +1,539 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
+- Add a `static constexpr const char * const VERSION` to the service class, for the service version.
+
+### C++ Bundles
+
+- Use `CamelCase` for C++ bundle target names.
+- Do _not_ use a `Celix` prefix for C++ bundle target names.
+- Use `celix::` prefixed aliases for C++ bundle targets.
+- Use `CamelCase` for C++ bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C++ bundle targets.
+- Use `Apache_Celix_` prefix for C++ bundle symbolic names.
+- Use `Apache Celix ` prefix for C++ bundle names.
+- Use a `celix_` prefix for C++ bundle filenames.
+- Use a group name starting with `celix/` for C++ bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(MyBundle
+ SOURCES src/MyBundle.cc
+ SYMBOLIC_NAME "Apache_Celix_MyBundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_MyBundle"
+ VERSION "1.0.0"
+ GROUP "celix/MyBundleGroup"
+)
+add_library(celix::MyBundle ALIAS MyBundle)
+```
+
+### Unit Tests Naming
+
+- The test fixture should have a`TestSuite` postfix.
+- The source file should be named after the test fixture name and use a `.cc` extension.
+- Testcase names should use `CamelCase` (starting with a capital) and have a `Test` postfix.
+- When using error injection (one of the `error_injector` libraries) a separate test suite should be used.
+ - A `ErrorInjectionTestSuite` postfix should be used for the test fixture.
+ - The error injection setup should be reset on the `TearDown` function or destructor of the test fixture.
+
+## Comments and Documentation
+
+- Use Doxygen for code documentation.
+- Write comments that explain the purpose of the code, focusing on the "why" rather than the "how".
+- Apply doxygen documentation to all public API's.
+- Use the javadoc style for doxygen documentation.
+- Use `@` instead of `\` for doxygen commands.
+- Start with a `@brief` command and a short description.
+- For `@param` commands also provide in, out, or in/out information.
+
+## Formatting and Indentation
+
+- Use spaces for indentation and use 4 spaces per indentation level.
+- Keep line lengths under 120 characters, if possible, to enhance readability.
+- Place opening braces on the same line as the control statement or function definition,
+ and closing braces on a new line aligned with the control statement or function definition.
+- Use a single space before and after operators and around assignment statements.
+- Add a space after control keywords (`if`, `for`, `while`, etc.) that are followed by a parenthesis.
+- Always use braces ({ }) for control structures, even for single-statement blocks, to prevent errors.
+- Add a space after control keywords (`else`, `do`, etc) that are followed by a brace.
+- Do not add a space after the function name and the opening parenthesis.
+- For new files apply clang-format using the project .clang-format file.
+ - Note that this can be done using a plugin for your IDE or by running `clang-format -i <file>`.
+
+## Control Structures
+
+- Use `if`, `else if`, and `else` statements to handle multiple conditions.
+- Use `switch` statements for multiple conditions with a default case.
+- Use `while` statements for loops that may not execute.
+- Use `do`/`while` statements for loops that must execute at least once.
+- Use `for` statements for loops with a known number of iterations.
+- The use of `goto` is not allowed, except for error handling.
+- For C, try to prevent deeply nested control structures and prefer early returns or error handling `goto` statements.
+ - To prevent deeply nested control structures, the `CELIX_DO_IF` and `CELIX_GOTO_IF_ERR` macros can also be used.
+
+## Functions and Methods
+
+- Limit functions to a single responsibility or purpose, following the Single Responsibility Principle (SRP).
+- Keep functions short and focused, aiming for a length of fewer than 50 lines.
+- Ensure const correctness.
+- For C functions with a lot of different parameters, consider using an options struct.
+ - An options struct combined with a EMPTY_OPTIONS macro can be used to provide default values and a such
+ options struct can be updated backwards compatible.
+ - An options struct ensure that a lot of parameters can be configured, but also direct set on creation.
+- For C++ functions with a lot of different parameters, consider using a builder pattern.
+ - A builder pattern can be updated backwards compatible.
+ - A builder pattern ensure that a lot of parameters can be configured, but also direct set on construction.
+
+## Error Handling and Logging
+
+- For C++, throw an exception when an error occurs.
+- For C, if memory allocation is needed or another error can occur, ensure that a function returns a value
+ than can be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- Use consistent error handling techniques, such as returning error codes or using designated error handling functions.
+- Log errors, warnings, and other important events using the Apache Celix log helper functions or - for libraries -
+ the `celix_err` (TBD) functionality.
+- Always check for errors and log them.
+- Ensure error handling is correct, using test suite with error injection.
+
+## Error Injection
+
+- Use the Apache Celix error_injector libraries to inject errors in unit tests in a controlled way.
+- Create a separate test suite for error injection tests.
+- Reset error injection setup on the `TearDown` function or destructor of the test fixture.
+- If an - internal or external - function is missing error injection support, add it to the error_injector library.
+ - Try to create small error injector libraries for specific functionality.
+
+## Unit Test Approach
+
+- Use the Google Test framework for unit tests.
+- Use the Google Mock framework for mocking.
+- Use the Apache Celix error_injector libraries to inject errors in unit tests in a controlled way.
+- Test bundles by installing them in a programmatically created framework.
+- Test bundles by using their provided services and used services.
+- In most cases, libraries can be tested using a white box approach and bundles can be tested using a black box approach.
+- For libraries that are tested with the Apache Celix error_injector libraries or require access to private/hidden
Review Comment:
Extended the sentence to:
"For libraries that are tested with the Apache Celix error_injector libraries or require access to private/hidden
functions (white-box testing), a separate "code under test" static library should be created."
So unit test which require access to prive/hidden function are allowed, should use a "_cut" lib and is (IMO) white-box testing.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "pnoltes (via GitHub)" <gi...@apache.org>.
pnoltes commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1216920855
##########
.clang-format:
##########
@@ -0,0 +1,27 @@
+BasedOnStyle: LLVM
+IndentWidth: 4
+AllowShortIfStatementsOnASingleLine: false
+AlwaysBreakTemplateDeclarations: Yes
+BinPackArguments: false
+BinPackParameters: false
+BreakBeforeBraces: Attach
+ColumnLimit: 120
+ConstructorInitializerIndentWidth: 4
+Cpp11BracedListStyle: true
+DerivePointerAlignment: false
+IncludeBlocks: Regroup
Review Comment:
I purpose to not regroup includes header for now.
I will leave this as comments, so that it can be used if desired on case per case basis.
If needed we can revisit this at a later stage.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Feature/coding conventions (celix)
Posted by "pnoltes (via GitHub)" <gi...@apache.org>.
pnoltes commented on code in PR #544:
URL: https://github.com/apache/celix/pull/544#discussion_r1187701954
##########
documents/development/README.md:
##########
@@ -0,0 +1,539 @@
+---
+title: Apache Celix Coding Conventions
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Apache Celix Coding Conventions
+Adhering to consistent and meaningful coding conventions is crucial for maintaining readable and maintainable code.
+This document outlines the recommended coding conventions for Apache Celix development, including naming conventions,
+formatting, comments, control structures, functions and error handling.
+
+Note that not all existing code adheres to these conventions.
+New code should adhere to these conventions and when possible, existing code should be updated to adhere to these
+conventions.
+
+## Naming Conventions
+
+### C/C++ Variables
+
+- Use `camelCase` for variable names.
+- Use descriptive names for variables.
+- Use `celix_` prefix or `celix::` (sub)namespace for global variables.
+- Asterisk `*` should be placed on the variable type name.
+
+### C Structures
+
+- Use `snake_case` for structure names.
+- Add a typedef for the structure.
+- Use a `_t` postfix for structure typedef.
+- Use `celix_` prefix for structure names.
+
+### C Functions
+
+- Use descriptive names for functions.
+- Use a `celix_` prefix.
+- Use a `_<obj>_` camelCase infix for the object/module name.
+- Use a postfix `camelCase` for the function name.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+Examples:
+- `long celix_bundleContext_installBundle(celix_bundle_context_t* ctx, const char* bundleUrl, bool autoStart)`
+- `bool celix_utils_stringEquals(const char* a, const char* b)`
+- `celix_status_t celix_utils_createDirectory(const char* path, bool failIfPresent, const char** errorOut)`
+
+### C Constants
+
+- Use `SNAKE_CASE` for constant names.
+- Use a `CELIX_` prefix for constant names.
+- Use `#define` for constants.
+
+### C Enums
+
+- Use `snake_case` for enum type names.
+- Use a `celix_` prefix for enum type names.
+- Use `SNAKE_CASE` for enum value names.
+- Use a `CELIX_` prefix for enum value names.
+- Add a typedef - with a `_e` postfix - for the enum
+
+Example:
+```c
+typedef enum celix_hash_map_key_type {
+ CELIX_HASH_MAP_STRING_KEY,
+ CELIX_HASH_MAP_LONG_KEY
+} celix_hash_map_key_type_e;
+```
+
+### Macros
+
+- Use all caps `SNAKE_CASE` for macro names.
+- Use a `CELIX_` prefix for macro names.
+
+### C files and directories
+
+- Use `snake_case` for file names.
+- Name header files with a `.h` extension and source files with a `.c` extension.
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- Google test files should be placed in a `gtest` directory with its own `CMakeLists.txt` file and `src` directory.
+- Use `celix_` prefix for header file names.
+- Use a header guard.
+- Use a C++ "extern C" block in headers file to ensure C headers are usable in C++.
+
+### C Libraries
+
+- Target names should be `snake_case`.
+- There should be `celix::` prefixed aliases for the library.
+- C Shared libraries should configure an output name with a `celix_` prefix.
+
+### C Services
+
+- Service headers should be made available through a CMake INTERFACE header-only api/spi library (i.e. `celix::shell_api`)
+- C service should be C struct, where the first member is the service handle (`void* handle;`) and the rest of the members are
+ function pointers.
+- The first argument of the service functions should be the service handle.
+- If memory allocation is needed or another error can occur in a service function, ensure that the return value can
+ be used to check for errors. This can be done by:
+ - Returning a `celix_status_t` and if needed using an out parameter.
+ - Returning a NULL pointer if the function returns a pointer type.
+ - Returning a boolean value, where `true` indicates success and `false` indicates failure.
+- In the same header as the C service struct, there should be defines for the service name and version.
+- The service name macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_NAME`.
+- The service version macro should be all caps `SNAKE_CASE`, prefixed with `CELIX_` and postfixed with `_VERSION`.
+- The value of the service name macro should be the service struct (so without a `_t` postfix
+- The value of the service version macro should be the version of the service.
+
+Example:
+```c
+//celix_foo.h
+#include "celix_errno.h"
+
+#define CELIX_FOO_NAME "celix_foo"
+#define CELIX_FOO_VERSION 1.0.0
+
+typedef struct celix_foo {
+ void* handle;
+ celix_status_t (*doFoo)(void* handle, char** outMsg);
+} celix_foo_t;
+```
+
+### C Bundles
+
+- Use `snake_case` for C bundle target names.
+- Do _not_ use a `celix_` prefix for C bundle target names.
+- Use `celix::` prefixed aliases for C bundle targets.
+- Use `snake_case` for C bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C bundle targets.
+- Use `apache_celix_` prefix for C bundle symbolic names.
+- Use `Apache Celix ` prefix for C bundle names.
+- Use a `celix_` prefix for C bundle filenames.
+- Use a group name starting with `celix/` for C bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(my_bundle
+ SOURCES src/my_bundle.c
+ SYMBOLIC_NAME "apache_celix_my_bundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_my_bundle"
+ VERSION "1.0.0"
+ GROUP "celix/my_bundle_group"
+)
+add_library(celix::my_bundle ALIAS my_bundle)
+```
+
+### C++ Classes
+
+- Use `CamelCase` (starting with a capital) for class names.
+- Use descriptive names for classes.
+- Classes should be part of a `celix::` namespace or sub `celix::` namespace.
+
+### C++ Functions
+
+- Use `camelCase` for function names.
+- If a function is not part of a class/struct, it should be part of a `celix::` namespace or sub `celix::` namespace.
+- Asterisk `*` should be placed on the variable type name.
+- Use verb as function names when a function has a side effect.
+- Use nouns or getter/setter as function names when a function does not have a side effect.
+- Use getters/setters naming convention for functions which get/set a value.
+
+
+### C++ Constants
+
+- Use `SNAKE_CASE` for constants.
+- Use constexpr for constants.
+- Place constants in a `celix::` namespace or sub `celix::` namespace.
+
+example:
+```c++
+namespace celix {
+ constexpr long FRAMEWORK_BUNDLE_ID = 0;
+ constexpr const char * const SERVICE_ID = "service.id";
+}
+```
+
+### C++ Enums
+
+- Use `CamelCase` (starting with a capital) for enum types names.
+- Use `enum class` instead of `enum`.
+- Use `SNAKE_CASE` for enum values without a celix/class prefix. Note that for enum values no prefix is required
+ because enum class values are scoped.
+
+Example:
+```c++
+namespace celix {
+ enum class ServiceRegistrationState {
+ REGISTERING,
+ REGISTERED,
+ UNREGISTERING,
+ UNREGISTERED
+ };
+}
+```
+
+### C++ files and directories
+
+- Use `CamelCase` (starting with a capital) for file names.
+- Name header files with a `.h` extension and source files with a `.cc` extension.
+- Place header files in a directory based on the namespace (e.g. `celix/Bundle.h`, `celix/dm/Component.h`).
+- Organize files in directories according to their purpose.
+ - Public headers files in a `include`, `api` or `spi` directory.
+ - Private header files in a `private` and `src` directory.
+ - Source files in a `src` directory.
+- For the Apache Celix framework and utils lib only header-only C++ files are allowed.
+- Prefer header-only C++ files for the Apache Celix libraries
+- Use a `#pragma once` header guard.
+
+### C++ Libraries
+
+- Target name should be `CamelCase` (starting with a capital).
+- There should be `celix::` prefixed aliases for the library.
+- C++ Libraries should support C++14.
+ - Exception are `celix::Promises` and `celix::PushStreams` which requires C++17.
+- C++ Libraries should prefer to be header-only.
+- C++ support for `celix::framework` and `celix::utils` must be header-only.
+- Header-only C++ libraries do not need an export header and do not need to configure symbol visibility.
+- C++ shared libraries (lib with C++ sources), should configure an output name with a `celix_` prefix.
+- C++ shared libraries (lib with C++ sources), should use an export header and configure symbol visibility.
+ - See the C Libraries section for more information.
+
+### C++ Services
+
+- Use `CamelCase` (starting with a capital) for service names.
+- Add a 'I' prefix to the service interface name.
+- Place service classes in a `celix::` namespace or sub `celix::` namespace.
+- Add a `static constexpr const char * const NAME` to the service class, for the service name.
+- Add a `static constexpr const char * const VERSION` to the service class, for the service version.
+
+### C++ Bundles
+
+- Use `CamelCase` for C++ bundle target names.
+- Do _not_ use a `Celix` prefix for C++ bundle target names.
+- Use `celix::` prefixed aliases for C++ bundle targets.
+- Use `CamelCase` for C++ bundle symbolic names.
+- Configure at least SYMBOLIC_NAME, NAME, FILENAME, VERSION and GROUP for C++ bundle targets.
+- Use `Apache_Celix_` prefix for C++ bundle symbolic names.
+- Use `Apache Celix ` prefix for C++ bundle names.
+- Use a `celix_` prefix for C++ bundle filenames.
+- Use a group name starting with `celix/` for C++ bundle groups.
+
+Examples:
+```cmake
+add_celix_bundle(MyBundle
+ SOURCES src/MyBundle.cc
+ SYMBOLIC_NAME "Apache_Celix_MyBundle"
+ NAME "Apache Celix My Bundle"
+ FILENAME "celix_MyBundle"
+ VERSION "1.0.0"
+ GROUP "celix/MyBundleGroup"
+)
+add_library(celix::MyBundle ALIAS MyBundle)
+```
+
+### Unit Tests Naming
+
+- The test fixture should have a`TestSuite` postfix.
+- The source file should be named after the test fixture name and use a `.cc` extension.
+- Testcase names should use `CamelCase` (starting with a capital) and have a `Test` postfix.
+- When using error injection (one of the `error_injector` libraries) a separate test suite should be used.
+ - A `ErrorInjectionTestSuite` postfix should be used for the test fixture.
+ - The error injection setup should be reset on the `TearDown` function or destructor of the test fixture.
+
+## Comments and Documentation
+
+- Use Doxygen for code documentation.
Review Comment:
Interesting, I have never considered this option.
Do you have a link to an example project for this.
Just lookup and apparently you can combine doxygen with plantuml, that could be a plus.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org