5

Is there any meaningful downside, on modern compilers, to putting comments starting at the beginning of a header file?

That is, something like the following in great_header.h:

/*
 * this file defines the secret to life
 * etc
 * (c) 2017 ascended being
 */

#pragma once
#ifndef NAMESPACE_GREAT_HEADER_H_
#define NAMESPACE_GREAT_HEADER_H_

... (actual contents)

#endif // ifndef NAMESPACE_GREAT_HEADER_H_

In the past, I remember caveats such as "#pragma once only first if it is the first line in the file", and similar rules for include-guard optimization - but I'm not sure if that is still the case. It would be convenient for me, and for automated tools which extract top-of-header info if comments could be the first thing in the file.

BeeOnRope
  • 60,350
  • 16
  • 207
  • 386
  • I would say that having the comments there will make the preprocessor run slightly longer time, as it has to skip it when reading the file... – Eugene Sh. Feb 03 '17 at 21:35
  • 1
    Why do you have `#pragma once` and include guards? Is it a *just to be sure* thing? – Iharob Al Asimi Feb 03 '17 at 21:35
  • Indeed. That's why I put "measurable" in there. In the past, to my understanding, the whole optimization for something like `#pragma once` was lost if it wasn't the first line. I'm not worried about the microseconds lost parsing the comments, but if an "include-once" type optimization was lost, so that the entire file, including all includes, was parsed, it would be a big deal. – BeeOnRope Feb 03 '17 at 21:36
  • 1
    @IharobAlAsimi - I have both because it is an example. In real life, I might be using one, or the other, or both (which isn't [necessarily stupid](http://stackoverflow.com/questions/13339392/should-i-still-use-include-guards-and-pragma-once)). The question is about whether comments can affect _either_ practice, or anything else too! – BeeOnRope Feb 03 '17 at 21:38
  • What would you be worried about? Speed of compilation? If so, it would only be the short amount of time it takes to scan through to the `#pragma once` line – Mobius Feb 03 '17 at 21:38
  • @Mobius - speed of compilation or anything else. If modern compilers just scan though to the `#pragma once` line that would be great info, good enough for an answer perhaps. As above, I'm not worried about scanning through the initial comments, but I am worried about disabling entire "include once" type optimizations entirely. – BeeOnRope Feb 03 '17 at 21:39
  • I believe that the real answer to your question has to include the phrase: "_implementation dependent_". (regarding how one or the other compiler handles comments, pragmas, etc.) There could be a different answer for each compiler implementation, so I would expect each answer to list exactly which compiler they are referencing. As long as a compiler implementation complies with the explicit specifications in the standard, they are free to implement non-specified features any way they choose. – ryyker Feb 03 '17 at 22:54
  • 1
    _measurable_ is an interesting word. Any detectable behavior change during a compilation (i.e. time duration, or assembly construction) is a measurable quantity. Do you really mean to say something like _meaningful_? (but then you are going to have the psychologists visiting the site to chime in) – ryyker Feb 03 '17 at 22:59
  • @ryyker - yes, I'm asking for a answer which covers modern implementations, which is why the first sentence includes the phase _"... on modern compilers ...". Of course, the idea is that all implementations have decided to implement this behavior in the same way, which makes it de-facto implementation independent, just like stuff covering platforms with non-twos-complement signed arithmetic, `char` larger than 8 bits, etc, etc. – BeeOnRope Feb 03 '17 at 23:00
  • @ryyker - fair, enough, if you want to be completely pedantic, _meaningful_ might be better (but that's also open to broad interpretation) - and so I replaced the word. I used _measurable_ in the sense of "big enough to show up in measurements with limited precision and variance". For example, if the pre-processor had to parse the comments, it is not likely this would show up as a statistically significant difference with tools that report time to 3 or 4 significant figures (or even with higher precision), since the `#pragma once` behavior prevents re-opening files. – BeeOnRope Feb 03 '17 at 23:05
  • @BeeOnRope - Yes, I kind of wrote that tongue in cheek, but all the same, its still a big assumption that _all_ modern compiler implementations do anything the same. As long as they are in the specification boundaries, implementation is open, and that can mean small (but measurable) differences in behavior. – ryyker Feb 03 '17 at 23:06
  • @ryyker - to be clear, I am not _assuming_ they all do things the same. I'm asking the question **Do they all do the things the same?** If any do not, the answer is "Yes, there is harm, on compiler XYZ". You want me to be completely explicit, let's consider the `gcc`, `clang` and `MSVC` toolchains, with `icc` thrown in for bonus points. – BeeOnRope Feb 03 '17 at 23:08

1 Answers1

6

According to GCC Preprocessor Internals manual, the multiple include optimization mechanism is not affected by comments:

The Multiple-Include Optimization

Under what circumstances is such an optimization valid? If the file were included a second time, it can only be optimized away if that inclusion would result in no tokens to return, and no relevant directives to process. Therefore the current implementation imposes requirements and makes some allowances as follows:

  1. There must be no tokens outside the controlling #if-#endif pair, but whitespace and comments are permitted.

It doesn't mention #pragma once there, which I suspect is treated separately. Referring to 2.5 Alternatives to Wrapper #ifndef:

Another way to prevent a header file from being included more than once is with the ‘#pragma once’ directive. If ‘#pragma once’ is seen when scanning a header file, that file will never be read again, no matter what.

ryyker
  • 22,849
  • 3
  • 43
  • 87
Grzegorz Szpetkowski
  • 36,988
  • 6
  • 90
  • 137