On 10.01.25 09:10, Peter Eisentraut wrote:
> On 02.01.25 17:15, Tom Lane wrote:
>>> It's a fair point that some documentation could be provided. I suppose
>>> we don't want to verbosely explain each pragma individually. Should
>>> there be some central explanation, maybe in src/tools/pginclude/README?
>>
>> That might do, but perhaps instead in the "PostgreSQL Coding
>> Conventions" chapter of the SGML docs? Actually, I think we could do
>> with a centralized explanation of our inclusion conventions --- I'm
>> not sure that the whole business of "postgres.h or a sibling must be
>> first" is explained in any easy-to-find place. This topic would
>> likely fit well with such an explanation.
>
> In this updated patch set, I've just added a bit of info into src/tools/
> pginclude/README. Updating the coding convention documentation like you
> suggest also sounds like a good idea, but from my perspective I would
> need to do further research to pin down what those actually are, so I'm
> leaving that as a separate project.
>
> (See for example the business in src/tools/pginclude/headerscheck about
> guessing which the appropriate first header file should be for each
> component. That kind of thing perhaps ought to be more formalized.)
>
>> But really, the point I was trying to make above is that I don't
>> want this to break our very long-standing convention that headers
>> should be #include'd alphabetically and there is never a need to
>> impose some other order (at least not without lots of commentary
>> about it at the scene of the crime). The way you've done it here
>> is just asking for trouble, IMO. If that means redundant pragma
>> commands, so be it.
>
> Yeah, that's a fair point. I have removed that part from my patch set.
I have committed this. Thanks for the feedback.
