Minimize over-inclusion to reduce accidental complexity in header files
- Dominant language
- C
- Stars
- 193
- Forks
- 99
- Avg merge
- 1m
- Merged PRs (30d)
- 1
Description
# Intro
If (public) header files include too much upstream header files, this can increase accidental complexity (accidental complexity arises when a software system becomes unnecessarily complicated due to factors that are not inherent to the problem being solved, but are rather a byproduct of the chosen tools, technologies, or approaches).
Several reasons over-inclusion add accidental complexity:
- Over-inclusion increases the compilation time as the compiler needs to process a larger set of dependencies
- Over-inclusion leads to a bloated and less maintainable codebase, where changes in one part of the system can have unforeseen ripple effects.
- Over-inclusion of headers can also inadvertently expose internal details to downstream users.
- Over-inclusion can lead to unintentionally backward incompatibility when header files are updated.
# Minimize symbols
An alternative to including a header file which contain many unneeded symbols is to use forward declaration or only include header files with a minimal number of symbols, forward declaration and/or opaque typedefs.
This will prevent adding to much unneeded symbols during a compilation of a source file and prevent downstream users to accidental/unintellionally get symbols they did not specifically include.
Note that creating header files with minimal symbols/forward-declaration/opaque-typedefs, can only be done for Apache Celix own header files.
# Tasks
## Update the coding guidelines
Update the coding guidelines so that functional coherent C header files are split up in multiple header files using something like the following scheme:
- The public api for a C functionality can can be found in a header named: `celix_.h`
- The opaque typedefs (forward declaration) can be found in a header named: `celix__type.h`. This header ideally should only contain opaque typedefs, but can also contain concrete struct definition if needed (e.g. celix_properties_entry_t or celix_properties_value_type_e, etc)
- If needed all private functions or structs (only used inside the library which provided the public api) can be found in a header named: `celix__private.h`. These header files should be in the `src` dir.
- If needed all internal functions or structs (only used inside the Apache Celix project, but not meant as public API), can be found in a header named: `celix__internal.h`. These header files should be in a separate `include_internal` dir and should only be added to a CMake target for the BUILD scope (not for install).
And functional coherent C++ header files are split up in multiple header files using something like the following scheme:
- The public api: `celix/Functionality.h`
- The forward declaration and minimal symbols: `celix/FunctionalityType.h`
- If needed a private header (in src dir): `celix/FunctionalityPrivate.h`
- if needed a internal header (in include_internal): `celix/FunctionalityInternal.h`
## Update framework and libs
Update at least the framework and libs to following the aforementioned updated header coding style. The bundles and bundle api/spi libs can be updated using a the last Boy Scout rule.
## Optional add build tooling to check include behaviour.
Maybe it is possible to use something like [include what you use tool](https://include-what-you-use.org) to check include behaviour.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.