From aa5a68be02bc2db23355c2420f80ee749821bffc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Joly?= Date: Fri, 29 Jul 2022 16:24:19 +0200 Subject: [PATCH] CPP-40 Make it clear that not using #pragma once is almost a stylistic choice --- rules/S1852/cfamily/metadata.json | 2 +- rules/S1852/cfamily/rule.adoc | 19 ++++--------------- 2 files changed, 5 insertions(+), 16 deletions(-) diff --git a/rules/S1852/cfamily/metadata.json b/rules/S1852/cfamily/metadata.json index 88f0e68b6e..8fb39ee33c 100644 --- a/rules/S1852/cfamily/metadata.json +++ b/rules/S1852/cfamily/metadata.json @@ -17,7 +17,7 @@ ] }, - "defaultSeverity": "Blocker", + "defaultSeverity": "Minor", "ruleSpecification": "RSPEC-1852", "sqKey": "S1852", "scope": "Main", diff --git a/rules/S1852/cfamily/rule.adoc b/rules/S1852/cfamily/rule.adoc index 17119201b2..0ad171910c 100644 --- a/rules/S1852/cfamily/rule.adoc +++ b/rules/S1852/cfamily/rule.adoc @@ -1,10 +1,10 @@ ``++#pragma once++`` is a preprocessor directive meant to ensure that a file is only included once in a compilation unit. However, there are several reasons to avoid it: -* While it is widely implemented, it's not universally supported. -* It's not part of the standard, so its behavior may vary from compiler to compiler. -* If the same file exists in two different locations, it will _not_ prevent the second file from being included in the compilation. +* It is not part of the standard, which prevents its use in some contexts. +* Even if it is supported by virtually all compilers, since its behavior is not defined, it may differ between compilers, especially for some corner cases when determining if two files are identical (for instance, in the presence of symbolic links). +* Its semantic is slightly different from the semantic of an include guard. For instance, if a file is duplicated in two different locations, `#pragma once` will not prevent multiple inclusion of this file. -For these reasons, include guards, or include guards along with ``++#pragma once++`` should be used instead. +Note: There used to be a build performance improvement when using `#pragma once` instead of an include guard because naive implementations of include guards need to parse the full file to get the `#endif` matching the `#if`. But most modern compilers specifically detect the include guard pattern and use a dedicated optimization that makes it about as fast as `#pragma once`. == Noncompliant Code Example @@ -27,17 +27,6 @@ For these reasons, include guards, or include guards along with ``++#pragma once ... #endif ---- -or - -[source,cpp] ----- -// my_header.h -#pragma once -#ifndef MY_HEADER -#define MY_HEADER -... -#endif ----- ifdef::env-github,rspecator-view[]