# RFC: rules for #include directives

- Thread: https://externals.io/message/119272
- Original archive: https://news-web.php.net/php.internals/119272
- Started by Max Kellermann on 2023-01-16T12:03:19+00:00
- Messages: 41
- Page 1 of 2: messages 1 to 25 (25 per page, add `?page=N` to the URL)
- Next page: https://externals.io/message/119272.md?page=2
- Reply by email to internals@lists.php.net
- More for agents: search with https://externals.io/search.md?q={query} · RFCs at https://externals.io/rfc.md · JSON API at https://externals.io/api · documentation at https://externals.io/llms.txt

---

## #119272 — Max Kellermann — 2023-01-16T12:03:19+00:00

URL: https://externals.io/message/119272#119272

Hi,

in the past weeks, I submitted four PRs for cleaning up the #includes
in the PHP code base:

 https://github.com/php/php-src/pull/10216
 https://github.com/php/php-src/pull/10220
 https://github.com/php/php-src/pull/10279
 https://github.com/php/php-src/pull/10300

I saw that the existing #include directives were inconsistent,
incomplete and bloated; things just worked by chance, not by design,
because there were a few headers which just included everything.  I
wanted to help clean up this mess that had accumulated over two
decades.

All PRs were welcomed by different reviewers and were merged; there
was just one minor criticism by Dmitry Stogov who thought the code
comments explaining many non-obvious #includes should be removed:

https://github.com/php/php-src/pull/10216#issuecomment-1375140255

> I don't think we should include the comments like // for
> BEGIN_EXTERN_C (and similar). The are good for review only.  I'm
> indifferent to these changes and don't object.

Yesterday, when a DTrace-specific regression was reported
(https://github.com/php/php-src/pull/10220#issuecomment-1383035139),
after which Dmitry asked to revert the whole PR:

 https://github.com/php/php-src/pull/10220#issuecomment-1383658247

Instead, I submitted a trivial fix for the regression
(https://github.com/php/php-src/pull/10334), which was rejected by
Dmitry
(https://github.com/php/php-src/pull/10220#issuecomment-1383706602)
but confirmed by the original reporter
(https://github.com/php/php-src/pull/10220#issuecomment-1383802334).

In spite of that, Dmitry demanded to revert all of my #include
cleanups
(https://github.com/php/php-src/pull/10220#issuecomment-1383739816):

> I'm asking to revert all these include cleanup commits!  This is
> just a useless permutation. e.g. 68ada76 adds typedef struct _* that
> we didn't need before. How is this clearly?

... which so far only Derick Rethans agreed to:

https://github.com/php/php-src/pull/10220#issuecomment-1383784480

> FWIW, I agree with Dmitry here, and these should all be reverted. It
> adds nothing but clutter.

Christoph M. Becker performed the revert and suggested doing an RFC
(https://github.com/php/php-src/pull/10220#issuecomment-1383789100)
and vote on it.

So this is a first draft of my proposal which I'd like to discuss with
you:

 https://github.com/php/php-src/pull/10338

Max

---

## #119273 — Kamil Tekiela — 2023-01-16T12:38:24+00:00

URL: https://externals.io/message/119272#119273 · In reply to: #119272

Hi,

Did you create an RFC already? Or is this RFC-like discussion?
In either case, if you are asking community to come to a decision, we need
to see some background. Why do you want to change this? What's the benefit?
What's the impact on other maintainers, especially extension maintainers?
Do you see any downsides to your new approach?

Regards,
Kamil

---

## #119274 — Dmitry Stogov — 2023-01-16T12:44:13+00:00

URL: https://externals.io/message/119272#119274 · In reply to: #119272

Hi Max,

Thanks for describing the situation.

We do not often vote on implementation changes that don't affect PHP
language itself.
At first, I even considered these changes as "I don't care".
However, they are turned up into huge patches that make troubles for PHP
maintenance.
As we didn't come to an agreement, the best decision should be done by the
PHP community.

In the current state of the implementation I'm personally against this, but
I might change my opinion if this is targeted to PHP-9 and the
implementation is done in a some better way.

Thanks. Dmitry.




> Hi,
>
> in the past weeks, I submitted four PRs for cleaning up the #includes
> in the PHP code base:
>
>  https://github.com/php/php-src/pull/10216
>  https://github.com/php/php-src/pull/10220
>  https://github.com/php/php-src/pull/10279
>  https://github.com/php/php-src/pull/10300
>
> I saw that the existing #include directives were inconsistent,
> incomplete and bloated; things just worked by chance, not by design,
> because there were a few headers which just included everything.  I
> wanted to help clean up this mess that had accumulated over two
> decades.
>
> All PRs were welcomed by different reviewers and were merged; there
> was just one minor criticism by Dmitry Stogov who thought the code
> comments explaining many non-obvious #includes should be removed:
>
> https://github.com/php/php-src/pull/10216#issuecomment-1375140255
>
> > […]
>
> Yesterday, when a DTrace-specific regression was reported
> (https://github.com/php/php-src/pull/10220#issuecomment-1383035139),
> after which Dmitry asked to revert the whole PR:
>
>  https://github.com/php/php-src/pull/10220#issuecomment-1383658247
>
> Instead, I submitted a trivial fix for the regression
> (https://github.com/php/php-src/pull/10334), which was rejected by
> Dmitry
> (https://github.com/php/php-src/pull/10220#issuecomment-1383706602)
> but confirmed by the original reporter
> (https://github.com/php/php-src/pull/10220#issuecomment-1383802334).
>
> In spite of that, Dmitry demanded to revert all of my #include
> cleanups
> (https://github.com/php/php-src/pull/10220#issuecomment-1383739816):
>
> > […]
>
> ... which so far only Derick Rethans agreed to:
>
> https://github.com/php/php-src/pull/10220#issuecomment-1383784480
>
> > […]
>
> Christoph M. Becker performed the revert and suggested doing an RFC
> (https://github.com/php/php-src/pull/10220#issuecomment-1383789100)
> and vote on it.
>
> So this is a first draft of my proposal which I'd like to discuss with
> you:
>
>  https://github.com/php/php-src/pull/10338
>
> Max
>
> --
> 
> To unsubscribe, visit: https://www.php.net/unsub.php

---

## #119275 — G. P. B. — 2023-01-16T12:48:54+00:00

URL: https://externals.io/message/119272#119275 · In reply to: #119272

> Hi,
>
> in the past weeks, I submitted four PRs for cleaning up the #includes
> in the PHP code base:
>
>  https://github.com/php/php-src/pull/10216
>  https://github.com/php/php-src/pull/10220
>  https://github.com/php/php-src/pull/10279
>  https://github.com/php/php-src/pull/10300
>
> I saw that the existing #include directives were inconsistent,
> incomplete and bloated; things just worked by chance, not by design,
> because there were a few headers which just included everything.  I
> wanted to help clean up this mess that had accumulated over two
> decades.
>
> All PRs were welcomed by different reviewers and were merged; there
> was just one minor criticism by Dmitry Stogov who thought the code
> comments explaining many non-obvious #includes should be removed:
>
> https://github.com/php/php-src/pull/10216#issuecomment-1375140255
>
> > […]
>
> Yesterday, when a DTrace-specific regression was reported
> (https://github.com/php/php-src/pull/10220#issuecomment-1383035139),
> after which Dmitry asked to revert the whole PR:
>
>  https://github.com/php/php-src/pull/10220#issuecomment-1383658247
>
> Instead, I submitted a trivial fix for the regression
> (https://github.com/php/php-src/pull/10334), which was rejected by
> Dmitry
> (https://github.com/php/php-src/pull/10220#issuecomment-1383706602)
> but confirmed by the original reporter
> (https://github.com/php/php-src/pull/10220#issuecomment-1383802334).
>
> In spite of that, Dmitry demanded to revert all of my #include
> cleanups
> (https://github.com/php/php-src/pull/10220#issuecomment-1383739816):
>
> > […]
>
> ... which so far only Derick Rethans agreed to:
>
> https://github.com/php/php-src/pull/10220#issuecomment-1383784480
>
> > […]
>
> Christoph M. Becker performed the revert and suggested doing an RFC
> (https://github.com/php/php-src/pull/10220#issuecomment-1383789100)
> and vote on it.
>
> So this is a first draft of my proposal which I'd like to discuss with
> you:
>
>  https://github.com/php/php-src/pull/10338
>
> Max
>

As the person who has signed off on the PRs and merged them, I am in favour
of these changes and think the revert is a total over reaction.
Before merging the first set, it was asked ahead of time if those changes
were OK, and multiple people were in favour of these changes.
The fact the DTrace build was broken inadvertently and only found out today
is a failure of our CI Build matrix and myself for not knowing this option
nor compiling with it.
Not of the changes.
Moreover, having those sorts of changes be RFCs seems counterproductive as
the only people who care about this are actual core and extensions
developers and this opens the gate for petty RFCs to resolve coding style
disagreements.

Finally, some of the wording used in those PR replies are far from civil
and can push away new contributors to the language.

Best regards,

George P. Banyard

---

## #119276 — Max Kellermann — 2023-01-16T12:53:59+00:00

URL: https://externals.io/message/119272#119276 · In reply to: #119273

> Did you create an RFC already? Or is this RFC-like discussion?

No.  I followed https://wiki.php.net/rfc/howto and this is step 1.
Creating the actual RFC is step 3.

(I'm new to PHP and this process - so far, I've only contributed PHP
code through GitHub, and I was surprised by today's sudden resistance
against my code cleanup by two PHP developers, after the others
welcomed by changes.)

> In either case, if you are asking community to come to a decision, we need
> to see some background.

> Why do you want to change this? What's the benefit?

For cleaner code, more readable code (less obscurity in huge amounts
of undocumented #includes), more correct code, less fragile code,
reduced compile times.

> What's the impact on other maintainers, especially extension
> maintainers?

Other maintainers may need to determine which includes they really
need, instead of relying on everything always already there by
including one random zend_* header.

Extension maintainers may see build failures because, for example,
they forgot to include errno.h but used "errno".  This previously
worked because all PHP headers included errno.h even though there was
no reason to.  These build failures are bugs in those extensions, and
revealing them is a good thing, even though it seems tedious at first.

> Do you see any downsides to your new approach?

Like any code cleanup, this can result in regressions for parts of PHP
that are not covered by a test and not built with the CI, like the
DTrace regression yesterday.

And code cleanups can easily reveal existing bugs, which is a good
thing, but those bugs can be hidden at first - e.g. failure to
explicitly include "php_config.h" will (silently) disable features and
break things.  That may cause some temporary pain, but in the end will
result in better code, though some will believe that it isn't a worthy
goal or not worth the temporary pain.

Derick Rethans wrote my idea "adds nothing but clutter", but I guess
he should explain what bothers him; I don't comprehend this, because
from my perspective, I intend to remove clutter.

Dmitry Stogov said it's "just a useless permutation", but I can't
understand this argument either.

Max

---

## #119282 — Chase Peeler — 2023-01-16T16:14:39+00:00

URL: https://externals.io/message/119272#119282 · In reply to: #119276

> 
> > […]
>
> No.  I followed https://wiki.php.net/rfc/howto and this is step 1.
> Creating the actual RFC is step 3.
>
> (I'm new to PHP and this process - so far, I've only contributed PHP
> code through GitHub, and I was surprised by today's sudden resistance
> against my code cleanup by two PHP developers, after the others
> welcomed by changes.)
>
> > […]
> need
> > […]
>
> > […]
>
> For cleaner code, more readable code (less obscurity in huge amounts
> of undocumented #includes), more correct code, less fragile code,
> reduced compile times.
>
> > […]
>
> Other maintainers may need to determine which includes they really
> need, instead of relying on everything always already there by
> including one random zend_* header.
>
> Extension maintainers may see build failures because, for example,
> they forgot to include errno.h but used "errno".  This previously
> worked because all PHP headers included errno.h even though there was
> no reason to.  These build failures are bugs in those extensions, and
> revealing them is a good thing, even though it seems tedious at first.
>
> > […]
>
> Like any code cleanup, this can result in regressions for parts of PHP
> that are not covered by a test and not built with the CI, like the
> DTrace regression yesterday.
>
> And code cleanups can easily reveal existing bugs, which is a good
> thing, but those bugs can be hidden at first - e.g. failure to
> explicitly include "php_config.h" will (silently) disable features and
> break things.  That may cause some temporary pain, but in the end will
> result in better code, though some will believe that it isn't a worthy
> goal or not worth the temporary pain.
>
> Derick Rethans wrote my idea "adds nothing but clutter", but I guess
> he should explain what bothers him; I don't comprehend this, because
> from my perspective, I intend to remove clutter.
>
> Dmitry Stogov said it's "just a useless permutation", but I can't
> understand this argument either.
>
> Max
>
> --
> 
> To unsubscribe, visit: https://www.php.net/unsub.php
>
>
For those of us that don't know the finer details of the build process,
will that have any impact on the final product such as reduced binary sizes
or better performance? I'm not saying that code cleanup isn't a good enough
reason to do this on its own, just curious if there are other advantages
beyond that.
-- 
Chase Peeler
chasepeeler@gmail.com

---

## #119283 — Max Kellermann — 2023-01-16T16:23:17+00:00

URL: https://externals.io/message/119272#119283 · In reply to: #119282

> will that have any impact on the final product such as reduced binary sizes
> or better performance?

No, this kind of code cleanup must not affect the resulting binary at
all, therefore no change to runtime behavior/performance.

Though the build will be faster, because the C compiler has fewer
includes (= less source code) to process in each compilation unit.

---

## #119284 — Kamil Tekiela — 2023-01-16T16:25:25+00:00

URL: https://externals.io/message/119272#119284 · In reply to: #119283

Have you done any benchmarking in terms of build time? Is there any
tangible difference or is it only theoretical?

---

## #119285 — tim@bastelstu.be — 2023-01-16T16:36:09+00:00

URL: https://externals.io/message/119272#119285 · In reply to: #119284

Hi


> Have you done any benchmarking in terms of build time? Is there any
> tangible difference or is it only theoretical?
> 

 From my experience contributing to another C project (HAProxy), 
cleaning up the the includes can have a measurable impact on build 
times. See this commit for example:

https://github.com/haproxy/haproxy/commit/340ef2502eae2a37781e460d3590982c0e437fbd

They go even as far as regularly reordering object files by build time 
to optimally keep multi-core machines busy to shave off the last few 
milliseconds:

https://github.com/haproxy/haproxy/commit/d2ff5dc3ebba1163749e2d874cce5892570f540a

Even for incremental build having a hypothetical 100ms decrease in build 
time can make the difference between "this is fast enough to wait" and 
"this is so slow that my mind wanders around while waiting to build". 
And in CI which doesn't do incremental builds we won't needlessly burn 
CPU time that is better spent elsewhere.

Thus I'm in favor of this cleanup.

Best regards
Tim Düsterhus

---

## #119286 — Max Kellermann — 2023-01-16T16:43:22+00:00

URL: https://externals.io/message/119272#119286 · In reply to: #119284

> Have you done any benchmarking in terms of build time? Is there any
> tangible difference or is it only theoretical?

I did, but in this early stage, there is no measurable speedup yet,
because there are still too many "fat" headers left that need to be
included everywhere, which in turn include too much.  The many small
improvements I made so far drown in that noise.

Once I have disentangled and splitted those fat headers (e.g. move
zend_result to a separate header to avoid including zend_types.h
everywhere), the speedup will be measurable and perceptible.  It's too
early to prove it with numbers.

---

## #119287 — tim@bastelstu.be — 2023-01-16T16:44:38+00:00

URL: https://externals.io/message/119272#119287 · In reply to: #119285

Hi


>   From my experience contributing to another C project (HAProxy),
> cleaning up the the includes can have a measurable impact on build
> times. See this commit for example:

Sorry for the duplicate mail, but it just came to my mind checking the 
CI build logs from before and after the revert:

-------------

Before (x64 Release ZTS)

https://github.com/php/php-src/actions/runs/3924250312/jobs/6708385711

After:

https://github.com/php/php-src/actions/runs/3929927482/jobs/6719316931

9:26 minutes -> 9:52 minutes

Before (x64 Debug NTS):

https://github.com/php/php-src/actions/runs/3924250312/jobs/6708385677

After:

https://github.com/php/php-src/actions/runs/3929927482/jobs/6719316800

4:14 minutes -> 5:11 minutes

-------------

So with the changes that already happened, Max managed to shave off 30 
seconds (5%) for the x64 Release ZTS build and 1 minute (19%) for the 
x64 Debug NTS build. This difference would likely become even larger, as 
to my understanding the cleanup wasn't complete yet.

Best regards
Tim Düsterhus

---

## #119289 — Levi Morrison via internals — 2023-01-16T17:22:14+00:00

URL: https://externals.io/message/119272#119289 · In reply to: #119272

As commented yesterday on one of the PRs, I strongly agree with the
cleanups. Our code has implicit dependencies and if you reorder the
includes in the same file, you can break builds. That shouldn't ever
happen.

I also agree that dtrace breaking is a failure of CI and testing, not
necessarily the patch (I haven't reviewed that PR carefully, maybe
there was some carelessness but if it's not tested, it's hard to blame
anyone).

Lastly, I do not care for the comments which explain why a header is
included. My experience is that these comments bitrot quite quickly.

Overall, I hope we can resume this effort.

---

## #119300 — Dmitry Stogov — 2023-01-18T08:45:42+00:00

URL: https://externals.io/message/119272#119300 · In reply to: #119289

Here are my comments about the last PR
https://github.com/php/php-src/pull/10345
Max asked to repost them in this thread:

In my opinion this should not be accepted.

Despite the intention is good, this huge patch doesn't improve anything but
adds new questions.

   - It introduces new include files (e.g. zend_char.h, what was wrong with
   zend_portability.h?)
   - It adds a lot of forward declarations (e.g. typedef struct _<type>
   <type>)
   - It adds almost useless comments that are not goigg to be kept as to
   date (e.g. #include "zend_portability.h" // for BEGIN_EXTERN_C,
   zend_portability.h defines all base macros for Zend engine)
   - zend.c adds a number of commented includes (is this some kind of TODO?)
   - <stdint.h>> is included in many other *.h files instead of single
   zend_portability.h or zend_types.h.

I see all these changes as a source permutation that don't add significant
value. On the other hand:

   - this may introduce PHP build failures on some untested configurations
   (like it was with DTRACE)
   - we have to support several PHP branches at once and merging fixes
   between very different branches is going to introduce problems
   - this changes may break compilation of third-party software (e.g.
   xdebug). Not a huge problem, but it's not great to do this in a minor
   version update.




On Mon, Jan 16, 2023 at 8:22 PM Levi Morrison via internals <
internals@lists.php.net> wrote:

> As commented yesterday on one of the PRs, I strongly agree with the
> cleanups. Our code has implicit dependencies and if you reorder the
> includes in the same file, you can break builds. That shouldn't ever
> happen.
>
> I also agree that dtrace breaking is a failure of CI and testing, not
> necessarily the patch (I haven't reviewed that PR carefully, maybe
> there was some carelessness but if it's not tested, it's hard to blame
> anyone).
>
> Lastly, I do not care for the comments which explain why a header is
> included. My experience is that these comments bitrot quite quickly.
>
> Overall, I hope we can resume this effort.
>
> --
> 
> To unsubscribe, visit: https://www.php.net/unsub.php

---

## #119301 — Max Kellermann — 2023-01-18T09:01:08+00:00

URL: https://externals.io/message/119272#119301 · In reply to: #119275

> Moreover, having those sorts of changes be RFCs seems counterproductive as
> the only people who care about this are actual core and extensions
> developers and this opens the gate for petty RFCs to resolve coding style
> disagreements.

How shall we proceed from here?  Shall I create an official RFC or
not?

George said no, which I understand; but I don't know what else to do
to produce a decision.

I asked Dmitry to post his GitHub arguments in this thread, so you see
both sides of the story, and you can discuss his arguments.  (I
already replied to him on GitHub, see
https://github.com/php/php-src/pull/10345)

Max

---

## #119302 — G. P. B. — 2023-01-18T11:51:28+00:00

URL: https://externals.io/message/119272#119302 · In reply to: #119301

> 
> > […]
> as
> > […]
>
> How shall we proceed from here?  Shall I create an official RFC or
> not?
>
> George said no, which I understand; but I don't know what else to do
> to produce a decision.
>
> I asked Dmitry to post his GitHub arguments in this thread, so you see
> both sides of the story, and you can discuss his arguments.  (I
> already replied to him on GitHub, see
> https://github.com/php/php-src/pull/10345)
>

I still don't think the RFC process is a good vehicle for those sorts of
decisions, but it's the only process we have and there is some clear
disagreement that needs to get resolved here.
So I think creating an official RFC is the only way.

Best regards,

George P. Banyard

---

## #119303 — Max Kellermann — 2023-01-18T11:58:16+00:00

URL: https://externals.io/message/119272#119303 · In reply to: #119302

> So I think creating an official RFC is the only way.

Okay then, I'm now at step 2 of https://wiki.php.net/rfc/howto

I registered the account "maxk" on the Wiki - please grant me RFC
karma!

Max

---

## #119304 — Christoph M. Becker — 2023-01-18T12:11:09+00:00

URL: https://externals.io/message/119272#119304 · In reply to: #119303

> 
> > […]
>
> Okay then, I'm now at step 2 of https://wiki.php.net/rfc/howto
>
> I registered the account "maxk" on the Wiki - please grant me RFC
> karma!

Done.  Best of luck!

--
Christoph M. Becker

---

## #119309 — Max Kellermann — 2023-01-18T14:55:23+00:00

URL: https://externals.io/message/119272#119309 · In reply to: #119304

> > […]
> 
> Done.  Best of luck!

Thanks.

Here's my RFC: https://wiki.php.net/rfc/include_cleanup

I hope that's correct this way - then we're now at step 5 "Listen to
the feedback, and try to answer/resolve all questions" - so please
give feedback :-)

---

## #119312 — tim@bastelstu.be — 2023-01-18T15:24:32+00:00

URL: https://externals.io/message/119272#119312 · In reply to: #119309

Hi


> Here's my RFC: https://wiki.php.net/rfc/include_cleanup
> 
> I hope that's correct this way - then we're now at step 5 "Listen to
> the feedback, and try to answer/resolve all questions" - so please
> give feedback :-)
> 

Don't forget to add it to the appropriate section in the RFC overview: 
https://wiki.php.net/rfc

Best regards
Tim Düsterhus

---

## #119315 — Derick Rethans — 2023-01-18T15:41:05+00:00

URL: https://externals.io/message/119272#119315 · In reply to: #119276

> 
> 
> > […]
> 
> Other maintainers may need to determine which includes they really
> need, instead of relying on everything always already there by
> including one random zend_* header.

Including a "random" zend header also sounds like a great benefit. I 
shouldn't need to care as an extension author which header enables which 
internal function(s) for usage.
 
> Extension maintainers may see build failures because, for example,
> they forgot to include errno.h but used "errno".  This previously
> worked because all PHP headers included errno.h even though there was
> no reason to.  These build failures are bugs in those extensions, and
> revealing them is a good thing, even though it seems tedious at first.

This is a very naive view of the world. You don't get to decide what is 
"good for other people".

> > […]
> 
…
> Derick Rethans wrote my idea "adds nothing but clutter", but I guess
> he should explain what bothers him; I don't comprehend this, because
> from my perspective, I intend to remove clutter.

When looking at the commit history, I saw more than a dozen commits 
doing a small change. That is clutter.

Adding forwards declarations for zend_* structs, is clutter.

Adding comments that go out of date as to why a header is included is 
also clutter.

> Dmitry Stogov said it's "just a useless permutation", but I can't 
> understand this argument either.

It creates code-churn, which makes merging up fixes from older branches 
harder. 

cheers,
Derick

---

## #119318 — Max Kellermann — 2023-01-18T16:07:52+00:00

URL: https://externals.io/message/119272#119318 · In reply to: #119315

> Including a "random" zend header also sounds like a great benefit. I 
> shouldn't need to care as an extension author which header enables which 
> internal function(s) for usage.

So, in your opinion, choosing an arbitrary of the 95 Zend/zend*.h
headers should make *all* functions available?

I don't agree with that.  Having a documented header such as
"zend_all.h" (or just the already-existing "php.h") which really makes
everything available is certainly a good idea.  But making all 95
headers behave that way doesn't sound like a good design.

> This is a very naive view of the world.

You make this personal.  Let's not.

> When looking at the commit history, I saw more than a dozen commits 
> doing a small change. That is clutter.

 https://github.com/php/php-src/blob/master/CONTRIBUTING.md

 "Do not commit multiple files and dump all messages in one commit. If
 you modified several unrelated files, commit each group separately
 and provide a nice commit message for each one."

Each of my commits is self-contained and cleans up one internal
library.  Exactly the way the PHP commit rules ask me to do.

I even took extra care so every commit is buildable, even though I had
to reorder them carefully to make that possible.  You may or may not
value my effort, but it is in line with PHP's rules.

> Adding forwards declarations for zend_* structs, is clutter.

That is a reasonable opinion, but not mine.

> Adding comments that go out of date as to why a header is included is 
> also clutter.

This argument puzzles me most.  I've never heard anybody criticize
some piece of code for having too MANY code comments, too MUCH
explanation.

Every piece of documentation/explanation eventually goes out of date,
but that's not a good reason to never write any.

> > […]
> 
> It creates code-churn, which makes merging up fixes from older branches 
> harder. 

I've been rebasing my include cleanup patches for several weeks and
have yet to see the first conflict.  That's because bug fixes merged
from the stable branches rarely ever affect #include directives.  And
even if there is some day a merge conflict, fixing it is trivial.

Max

---

## #119323 — Rowan Tommins — 2023-01-18T17:06:26+00:00

URL: https://externals.io/message/119272#119323 · In reply to: #119318

Regards,

>This argument puzzles me most.  I've never heard anybody criticize
>some piece of code for having too MANY code comments, too MUCH
>explanation.

Then I guess you've never heard people quoting Robert "Uncle Bob" Martin, who is well known for asserting that code should be self-documenting, and therefore not need comments, saying things like:

> The proper use of comments is to compensate for our failure to express ourself in code. Note that I used the word failure. I meant it. Comments are always failures.

Many arguments could be had over whether that's going too far, but "too many comments" can definitely be a bad thing.

To take the example Dmitry gave:

> #include "zend_portability.h" // for BEGIN_EXTERN_C

What should I understand from this comment?

- If I want some other symbol defined in zend_portability.h, do I need to adjust the includes? No, all the symbols are already imported. I could adjust the comment, but nothing will break if I don't.
- If I remove the last use of BEGIN_EXTERN_C in this file, can I remove the include? No, because other symbols from it might be used, even if they weren't when the comment was written.

So why does this comment feel necessary?

- Perhaps the name of the header doesn't give a clear enough idea of what symbols it might contain, and what types of file should include it. If so, concentrate on better naming, or better documentation of existing conventions.
- Perhaps it is a justification added when the include was first added. If so, put it in the commit message and PR summary.

I'm not the right person to have opinions on the rest of this discussion, but I can certainly understand the argument against this particular aspect.

-- 
Rowan Tommins
[IMSoP]

---

## #119326 — Kamil Tekiela — 2023-01-18T17:51:53+00:00

URL: https://externals.io/message/119272#119326 · In reply to: #119323

I am in both camps. I think some slight cleanup might be in order, but not
how you are proposing it. First of all:
- I am against forward struct declarations. I think they decrease code
readability and should be avoided.
- I am against putting comments on #includes. Comments are noise in code
and often go out of date. Especially in a situation like this where the
comment is physically far away from the code that introduced it. To take
the example:
> #include "zend_portability.h" // for BEGIN_EXTERN_C
What if in future the need for BEGIN_EXTERN_C disappears? Who is going to
remember to update the comment?

As you said yourself, this refactoring has no practical effect on
compilation times. But your RFC states this as one of the advantages. This
is misleading.
Another advantage listed is "more correct code". Perhaps it is, but does it
mean that the current situation is likely to cause more frequent PHP bugs?
Would this refactoring help in finding PHP bugs more quicker?

Others have raised a valid point that PHP bugs are fixed in earlier
versions and then merged up into master. What you are proposing is going to
lead to issues with merging. And I don't mean merge conflicts, because
includes rarely change in bug fixes. I mean things like a bug fix using a
symbol that hasn't been used in the file but is included through one of the
more generic headers. Once such a commit is merged into master, it may turn
out that the symbol lacks a new include. This adds unnecessary work for bug
fixers who will now have to verify this and find the appropriate include
during merges.

So maybe reduce scope of this refactoring? Do it only where it's strictly
necessary. Don't use forward declarations or comments. Or maybe have all
ZEND headers included with a single header? Refactoring needs to make
developers' life easier and not just be done for the sake of following
best-practice.

---

## #119329 — tim@bastelstu.be — 2023-01-18T19:17:13+00:00

URL: https://externals.io/message/119272#119329 · In reply to: #119326

Hi


> As you said yourself, this refactoring has no practical effect on

It has no practical effect *yet*. The headers need to be untangled first 
before actual optimization can happen.
> Or maybe have all
> ZEND headers included with a single header?

That would go against the goal of reducing compile times. Much of the 
time spent when compiling C is parsing megabytes of source code, because 
deeply nested and/or unnecessary includes will bloat the amount of code 
the toolchain will need to go through.

Let me give a simple example:

We have the following headers:

a.h: 1 MB.
b.h: Includes a.h and is itself 100 kB in size.
c.h: Includes a.h and is itself 100 kB in size.

foo.c: Includes b.h and c.h, but c.h is not actually used. Is itself 300 
kB in size.

Now when compiling foo.c, a total of 2.5 MB of source code need to be 
parsed, because a.h is included twice. If the unused include for c.h is 
removed, then it will only be 1.4 MB in total. This multiplies quickly 
for more complex include chains. I'd like to point to this commit once more:

https://github.com/haproxy/haproxy/commit/340ef2502eae2a37781e460d3590982c0e437fbd

Removing two headers in a single file reduced the total compile by 
roughly 10%!

Here's two more similar commits:

https://github.com/haproxy/haproxy/commit/e5983ffb3adbf71a8f286094b1c1afce6061d1f3
https://github.com/haproxy/haproxy/commit/1db546eecd3982ffc1ea92c2f542a3b01ce43137

Best regards
Tim Düsterhus

---

## #119336 — flaviohbatista@gmail.com — 2023-01-18T20:37:43+00:00

URL: https://externals.io/message/119272#119336 · In reply to: #119329

> Hi
>
> 
> > […]
>
> It has no practical effect *yet*. The headers need to be untangled first
> before actual optimization can happen.
> > […]
>
> That would go against the goal of reducing compile times. Much of the
> time spent when compiling C is parsing megabytes of source code, because
> deeply nested and/or unnecessary includes will bloat the amount of code
> the toolchain will need to go through.
>
> Let me give a simple example:
>
> We have the following headers:
>
> a.h: 1 MB.
> b.h: Includes a.h and is itself 100 kB in size.
> c.h: Includes a.h and is itself 100 kB in size.
>
> foo.c: Includes b.h and c.h, but c.h is not actually used. Is itself 300
> kB in size.
>
> Now when compiling foo.c, a total of 2.5 MB of source code need to be
> parsed, because a.h is included twice. If the unused include for c.h is
> removed, then it will only be 1.4 MB in total. This multiplies quickly
> for more complex include chains. I'd like to point to this commit once
> more:
>
>
> https://github.com/haproxy/haproxy/commit/340ef2502eae2a37781e460d3590982c0e437fbd
>
> Removing two headers in a single file reduced the total compile by
> roughly 10%!
>
> Here's two more similar commits:
>
>
> https://github.com/haproxy/haproxy/commit/e5983ffb3adbf71a8f286094b1c1afce6061d1f3
>
> https://github.com/haproxy/haproxy/commit/1db546eecd3982ffc1ea92c2f542a3b01ce43137
>
> Best regards
> Tim Düsterhus
>
> --
> 
> To unsubscribe, visit: https://www.php.net/unsub.php
>
>
Tim,

This may be a silly question, but in that case, wouldn't #ifdef guards keep
the compiler from including/parsing a.h twice?

When a.h is *not* required by any of b.h, c.h nor foo.c, I agree that it
should *not* be included at all, but when any of them,
or even if all of them requires it, the guards should be enough to avoid
redundant work afaik.

Or am I missing anything here?

---

Next page: https://externals.io/message/119272.md?page=2
