From 0cc98e4efeecb7301e40f98c02228271c1d40dd1 Mon Sep 17 00:00:00 2001 From: Carles Cufi Date: Thu, 3 Nov 2022 17:49:12 +0100 Subject: [PATCH] doc: coding guidelines: Add a new rule for macro name collisions This commit is the outcome of the discussion that has taken place in multiple forums: Discord: https://discord.com/channels/720317445772017664/1014241011989487716/1032623375228608522 GitHub: https://github.com/zephyrproject-rtos/zephyr/issues/51371 https://github.com/zephyrproject-rtos/zephyr/pull/50239 (cherry picked from commit d095f7d22fbfb3dda5ec0142ceef208168597cb7) Original-Signed-off-by: Carles Cufi GitOrigin-RevId: d095f7d22fbfb3dda5ec0142ceef208168597cb7 Change-Id: I473d1b1f55da92b34bd429cd60f0cf75488ed5d4 Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/third_party/zephyr/+/4287511 Tested-by: Keith Short Reviewed-by: Keith Short Tested-by: Al Semjonovs Commit-Queue: Al Semjonovs Tested-by: CopyBot Service Account Reviewed-by: Al Semjonovs --- doc/contribute/coding_guidelines/index.rst | 42 ++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/doc/contribute/coding_guidelines/index.rst b/doc/contribute/coding_guidelines/index.rst index b4ed5a84560..6f53017fb29 100644 --- a/doc/contribute/coding_guidelines/index.rst +++ b/doc/contribute/coding_guidelines/index.rst @@ -1255,6 +1255,48 @@ Related GitHub Issues and Pull Requests are tagged with the `Inclusive Language .. _CAN in Automation Inclusive Language news post: https://www.can-cia.org/news/archive/view/?tx_news_pi1%5Bnews%5D=699&tx_news_pi1%5Bday%5D=6&tx_news_pi1%5Bmonth%5D=12&tx_news_pi1%5Byear%5D=2020&cHash=784e79eb438141179386cf7c29ed9438 .. _CAN in Automation Inclusive Language: https://can-newsletter.org/canopen/categories/ + +Rule A.3: Macro name collisions +=============================== + +Severity +-------- + +Required + +Description +----------- + +Macros with commonly used names such as ``MIN``, ``MAX``, ``ARRAY_SIZE``, must +not be modified or protected to avoid name collisions with other +implementations. In particular, they must not be prefixed to place them in a +Zephyr-specific namespace, re-defined using ``#undef``, or conditionally +excluded from compilation using ``#ifndef``. Instead, if a conflict arises with +an existing definition originating from a :ref:`module `, the module's +code itself needs to be modified (ideally upstream, alternatively via a change +in Zephyr's own fork). +This rule applies to Zephyr as a project in general, regardless of the time of +introduction of the macro or its current name in the tree. If a macro name is +commonly used in several other well-known open source projects then the +implementation in Zephyr should use that name. While there is a subjective and +non-measurable component to what "commonly used" means, the ultimate goal is +to offer users familiar macros. +Finally, this rule applies to inter-module name collisions as well: in that case +both modules, prior to their inclusion, should be modified to use +module-specific versions of the macro name that collides. + +Rationale +--------- + +Zephyr is an RTOS that comes with additional functionality and dependencies in +the form of modules. Those modules are typically independent projects that may +use macro names that can conflict with other modules or with Zephyr itself. +Since, in the context of this documentation, Zephyr is considered the central or +main project, it should implement the non-namespaced versions of the +macros. Given that Zephyr uses a fork of the corresponding upstream for each +module, it is always possible to patch the macro implementation in each module +to avoid collisions. + Parasoft Codescan Tool **********************