Skip to content

Modify rule S1003: Update description #4016

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jul 10, 2024
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 14 additions & 5 deletions rules/S1003/cfamily/rule.adoc
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
== Why is this an issue?

A using directive makes names from another namespace available in the current scope. It should only be used when those names do not create an ambiguity with other names, otherwise, it is better to fully qualify the names you want to use.
A using-directive (e.g., `using namespace std;`) makes names from another namespace available in the current scope. It should only be used when those names do not create an ambiguity with other names. Otherwise, it is better to fully qualify the names you want to use.

When you write a header file, you don't know from which context it will be included. Therefore, if this header contains using-directives, you cannot be sure that they will not create ambiguities in that context. Those ambiguities could lead to compilation failures or, worse, to a different function being selected by overload resolution depending on the order of inclusion of headers.

When you write a header file, you don't know from which context it will be included. Therefore, if this header contains using directives, you cannot be sure that they will not create ambiguities in that context. Those ambiguities could lead to compilation failures or, worse, to a different function being selected by overload resolution depending on the order of inclusion of headers.
The effect of using-directives used inside a function body ceases at the end of the current scope and, therefore, doesn't propagate to the users of the header file.


A using declaration behaves in the same way but only for one name. Because of their much narrower scope, this rule does not apply to using declarations.
However, when the using-directives are at the global or namespace scope of header files, their effects propagate to the files that include them. This rule will raise an issue on those using-directives.


=== Noncompliant code example
Expand Down Expand Up @@ -52,12 +52,21 @@ void m2 ( )

=== Exceptions

The issue only happens if the using directive is at global scope or at namespace scope. If is is inside a function body, it will cease to be in effect at the end of the current scope, and will not propagate to the users of the header file.
A using-declaration (e.g., `using std::cout;`) behaves in the same way but only for one name. Because their scope is much narrower, this rule does not apply to using-declarations.

Additionally, since it isn't easy to fully qualify the content of the `std::literals` and `std::placeholders` namespaces, this rule doesn't raise violations for using-directives that target these namespaces or their sub-namespaces, such as ``++std::literals::chrono_literals++``.

== Resources

=== Documentation

* {cpp} reference - https://en.cppreference.com/w/cpp/language/namespace#Using-directives[using-directives]


=== External coding guidelines

* MISRA {cpp}:2008, 7-3-6 - using-directives and using-declarations (excluding class scope or function scope using-declarations) shall not be used in header files.

* {cpp} Core Guidelines - https://github.com/isocpp/CppCoreGuidelines/blob/e49158a/CppCoreGuidelines.md#sf7-dont-write-using-namespace-at-global-scope-in-a-header-file[SF.7: Don't write `using namespace` at global scope in a header file]


Expand Down