[Coding Guideline]: Do not hide unsafe code in macros

[rcseacord]

Chapter

Macros

Guideline Title

Do not hide unsafe code in macros

Category

Advisory

Status

Draft

Release Begin

unclear

Release End

latest

FLS Paragraph ID

fls_83182bfa9uqb

Decidability

Decidable

Scope

Module

Tags

safety

Amplification

Do not hide unsafe code in macro definitions.
Macros that expand to unsafe code should preserve the unsafe token visibility.

Exception(s)

No response

Rationale

Macros that generate unsafe code obscure safety-critical code, making the code more difficult to review and audit.

Non-Compliant Example 1 - Prose

Macros that generate unsafe code without preserving the unsafe token visibility obscure safety-critical code from auditors and static analysis tools.

Non-Compliant Example 1 - Code

            // This macro hides the unsafe token from callers - noncompliant
            macro_rules! deref_ptr {
                ($ptr:expr) => {
                    unsafe { *$ptr }
                };
            }

            fn main() {
                let x = 42;
                let ptr = &x as *const i32;
                // The unsafe operation is hidden from the caller
                println!("val = {}", deref_ptr!(ptr));
            }

Non-Compliant Example 2 - Prose (Optional)

No response

Non-Compliant Example 2 - Code (Optional)

No response

Non-Compliant Example 3 - Prose (Optional)

No response

Non-Compliant Example 3 - Code (Optional)

No response

Non-Compliant Example 4 - Prose (Optional)

No response

Non-Compliant Example 4 - Code (Optional)

No response

Compliant Example 1 - Prose

This compliant example requires the caller to wrap the macro invocation in an unsafe block, making the use of unsafe code obvious at the call site.
Visibility can be further improved by prefixing the identifier for each unsafe macro with the string "unsafe_"

Compliant Example 1 - Code

            // This macro requires the caller to acknowledge the unsafe operation - compliant
            macro_rules! unsafe_deref_ptr {
                ($ptr:expr) => {
                    *$ptr
                };
            }

            fn main() {
                let x = 42;
                let ptr = &x as *const i32;
                // The unsafe operation is visible at the call site
                let val = unsafe { unsafe_deref_ptr!(ptr) };
                println!("val = {}", val);
            }

Compliant Example 2 - Prose (Optional)

No response

Compliant Example 2 - Code (Optional)

No response

Compliant Example 3 - Prose (Optional)

No response

Compliant Example 3 - Code (Optional)

No response

Compliant Example 4 - Prose (Optional)

No response

Compliant Example 4 - Code (Optional)

No response

Bibliography

No response

[github-actions]

📋 RST Preview for Coding Guideline

This is an automatically generated preview of your coding guideline in reStructuredText format.

📁 Target Location

Create a new file: src/coding-guidelines/macros/gui_yQC2tSE2Qeii.rst.inc

Note: The .rst.inc extension prevents Sphinx from auto-discovering the file.
It will be included via the chapter's index.rst.

We add it to this path, to allow the newly added guideline to appear in the correct chapter.

🗂️ Update Chapter Index

Update src/coding-guidelines/macros/index.rst to include gui_yQC2tSE2Qeii.rst.inc, like so:

Chapter Name Here <- chapter heading inside of `src/coding-guidelines/macros/index.rst`
=================

.. include:: gui_7y0GAMmtMhch.rst.inc -| existing guidelines
.. include:: gui_ADHABsmK9FXz.rst.inc  |
...                                    |
...                                    |
.. include:: gui_RHvQj8BHlz9b.rst.inc  |
.. include:: gui_dCquvqE1csI3.rst.inc -|
.. include:: gui_yQC2tSE2Qeii.rst.inc <- your new guideline to add

🧪 Code Example Test Results

✅ All 2 code example(s) compiled successfully!

Note: Code examples are tested with rustc --edition=2021.
Hidden lines (prefixed with # ) are included in compilation.
Examples without a fn main() are automatically wrapped.

📝 How to Use This

1. Fork the repository (if you haven't already) and clone it locally
2. Create a new branch from main:

   git checkout main
   git pull origin main
   git checkout -b guideline/your-descriptive-branch-name

3. Create the guideline file:

   mkdir -p src/coding-guidelines/macros

4. Copy the RST content below into a new file named gui_yQC2tSE2Qeii.rst.inc
5. Update the chapter index - Add an include directive to src/coding-guidelines/macros/index.rst:

   .. include:: gui_yQC2tSE2Qeii.rst.inc

   Keep the includes in alphabetical order by guideline ID.
6. Build locally to verify the guideline renders correctly:

   ./make.py

7. Commit and push your changes:

   git add src/coding-guidelines/macros/
   git commit -m "Add guideline: <your guideline title>"
   git push origin guideline/your-descriptive-branch-name

8. Open a Pull Request against main

📄 Click to expand RST content

.. SPDX-License-Identifier: MIT OR Apache-2.0
   SPDX-FileCopyrightText: The Coding Guidelines Subcommittee Contributors

.. guideline:: Do not hide unsafe code in macros
    :id: gui_yQC2tSE2Qeii
    :category: advisory
    :status: draft
    :release: unclear-latest
    :fls: fls_83182bfa9uqb
    :decidability: decidable
    :scope: module
    :tags: safety

    Do not hide unsafe code in macro definitions. Macros that expand to unsafe code should preserve the ``unsafe`` token visibility.

    .. rationale::
        :id: rat_s7ffMlPUFt77
        :status: draft

        Macros that generate unsafe code obscure safety-critical code, making the code more difficult to review and audit.

    .. non_compliant_example::
        :id: non_compl_ex_YNX7AnWENTu7
        :status: draft

        Macros that generate unsafe code without preserving the ``unsafe`` token visibility obscure safety-critical code from auditors and static analysis tools.

        .. rust-example::

            // This macro hides the unsafe token from callers - noncompliant
            macro_rules! deref_ptr {
                ($ptr:expr) => {
                    unsafe { *$ptr }
                };
            }

            fn main() {
                let x = 42;
                let ptr = &x as *const i32;
                // The unsafe operation is hidden from the caller
                println!("val = {}", deref_ptr!(ptr));
            }


    .. compliant_example::
        :id: compl_ex_nBkfzueTWvTA
        :status: draft

        This compliant example requires the caller to wrap the macro invocation in an ``unsafe`` block, making the use of unsafe code obvious at the call site. Visibility can be further improved by prefixing the identifier for each unsafe macro with the string “unsafe\_”

        .. rust-example::

            // This macro requires the caller to acknowledge the unsafe operation - compliant
            macro_rules! unsafe_deref_ptr {
                ($ptr:expr) => {
                    *$ptr
                };
            }

            fn main() {
                let x = 42;
                let ptr = &x as *const i32;
                // The unsafe operation is visible at the call site
                let val = unsafe { unsafe_deref_ptr!(ptr) };
                println!("val = {}", val);
            }

---

_{🤖 This comment was automatically generated from the issue content. It will be updated when you edit the issue body.}

[felix91gr]

@rcseacord this shouldn't be too painful, but there's an existing stub rule about not hiding unsafe code in macros. Whenever you open a PR for this, could I ask you to modify the existing rule instead of creating a new one? :) just so that we don't have a Retired rule later with the same name and intent as this one

[rcseacord]

@felix91gr I didn't even know we allowed stubs to be published.
I moved this content to stub and create this PR
#368

[rcseacord]

Closing this issue now that we have a PR for it.
#368

[felix91gr]

@felix91gr I didn't even know we allowed stubs to be published. I moved this content to stub and create this PR #368

@rcseacord

We don't. It's... just a very old guideline, from when the project was barely a couple of people and enthusiasm.

Many of the existing macro rules are like that: incomplete. Well, I guess that's why I'm writing an issue for most of them: #363