[Clang-Tidy] Add discussion to portability-avoid-pragma-once

[SunBlack]

In #140388, a check was added that recommends replacing #pragma once with include guards. From a portability perspective, this is correct. However, there are also good reasons for #pragma once: It is not as susceptible to copy & paste errors or renaming errors.

I have now looked at only a few headers in this repo, and you can always find minor errors that were not detected even with llvm-header-guard – and as you can see in #66477, such errors happen more often if you don't have a dedicated test for them (which few projects are likely to have). As long as there is no generic check for this (which would be difficult), errors like this one #29221 are likely to occur.

Example for not uniform include guards here:

llvm-project/clang-tools-extra/clang-tidy/modernize/UseStdPrintCheck.h

Lines 9 to 10 in 29b6433

	#ifndef LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_USESTDPRINTCHECK_H
	#define LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_USESTDPRINTCHECK_H

vs (misses the word check and also different handling of the pascal case conversion)

llvm-project/clang-tools-extra/clang-tidy/modernize/UseUsingCheck.h

Lines 9 to 10 in 29b6433

	#ifndef LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_MODERNIZE_USE_USING_H
	#define LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_MODERNIZE_USE_USING_H

Therefore, I would suggest adding a brief discussion to the documentation:

• If portability and all possible edge cases are a high priority => include guard
• In "simple" projects, #pragma once is also perfectly fine, as it prevents macro naming errors
• In C++20 projects, switching to modules can be an alternative (including a note that compiler support is still limited)

So basically I just miss a hint, that header guards also have their disadvantages (and not only #prama once).

[llvmbot]

@llvm/issue-subscribers-clang-tidy

Author: SunBlack (SunBlack)

In #140388, a check was added that recommends replacing `#pragma once` with include guards. From a portability perspective, this is correct. However, there are also good reasons for `#pragma once`: It is not as susceptible to copy & paste errors or renaming errors.

I have now looked at only a few headers in this repo, and you can always find minor errors that were not detected even with llvm-header-guard – and as you can see in #66477, such errors happen more often if you don't have a dedicated test for them (which few projects are likely to have). As long as there is no generic check for this (which would be difficult), errors like this one #29221 are likely to occur.

Example for not uniform include guards here:

llvm-project/clang-tools-extra/clang-tidy/modernize/UseStdPrintCheck.h

Lines 9 to 10 in 29b6433

	#ifndef LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_USESTDPRINTCHECK_H
	#define LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_USESTDPRINTCHECK_H

vs (misses the word check)

llvm-project/clang-tools-extra/clang-tidy/modernize/UseUsingCheck.h

Lines 9 to 10 in 29b6433

	#ifndef LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_MODERNIZE_USE_USING_H
	#define LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_MODERNIZE_USE_USING_H

Therefore, I would suggest adding a brief discussion to the documentation:

• If portability and all possible edge cases are a high priority => include guard
• In "simple" projects, #pragma once is also perfectly fine, as it prevents macro naming errors
• In C++20 projects, switching to modules can be an alternative (including a note that compiler support is still limited)

So basically I just miss a hint, that header guards also have their disadvantages (and not only #prama once).

[vbvictor]

CC @dl8sd11 If you wish to update docs a little.
To me, this is a great improvement overall for a new project, who would choose pragma once vs header guard.

[LegalizeAdulthood]

and as you can see in #66477, such errors happen more often if you don't have a dedicated test for them

I would have failed that in code review as it introduces double underscores in user identifiers; all identifiers containing a double underscore are reserved.

https://en.cppreference.com/w/cpp/language/identifiers.html