Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:119323
Date: Wed, 18 Jan 2023 17:06:26 +0000
To: internals@lists.php.net
User-Agent: K-9 Mail for Android
In-Reply-To: <Y8gZWLQd1SvL6a3n@swift.blarg.de>
References: <Y8U9B4AVP/R7vazI@swift.blarg.de> <CAGBsUrdQAXE2qk_UDQY9v6pYpWH+=bX6S3ou+sttQamtDC1F9A@mail.gmail.com> <Y8VI5yanzli8D4Cm@swift.blarg.de> <alpine.DEB.2.23.453.2301181536160.23089@singlemalt.home.derickrethans.nl> <Y8gZWLQd1SvL6a3n@swift.blarg.de>
Message-ID: <8DA390C5-5E67-4847-A89F-1A8CCC6C5389@gmail.com>
MIME-Version: 1.0
Content-Type: multipart/alternative;
 boundary=----1FJU0L4DTRCB3RZK8ZNOTVQFNC45R4
Content-Transfer-Encoding: 7bit
Subject: Re: [PHP-DEV] RFC: rules for #include directives
From: rowan.collins@gmail.com (Rowan Tommins)

------1FJU0L4DTRCB3RZK8ZNOTVQFNC45R4
Content-Type: text/plain;
 charset=utf-8
Content-Transfer-Encoding: quoted-printable

Regards,
On 18 January 2023 16:07:52 GMT, Max Kellermann <max+php@blarg=2Ede> wrote=
:
>This argument puzzles me most=2E  I've never heard anybody criticize
>some piece of code for having too MANY code comments, too MUCH
>explanation=2E

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 t=
herefore not need comments, saying things like:

> The proper use of comments is to compensate for our failure to express o=
urself in code=2E Note that I used the word failure=2E I meant it=2E Commen=
ts are always failures=2E

Many arguments could be had over whether that's going too far, but "too ma=
ny comments" can definitely be a bad thing=2E

To take the example Dmitry gave:

> #include "zend_portability=2Eh" // for BEGIN_EXTERN_C

What should I understand from this comment?

- If I want some other symbol defined in zend_portability=2Eh, do I need t=
o adjust the includes? No, all the symbols are already imported=2E I could =
adjust the comment, but nothing will break if I don't=2E
- If I remove the last use of BEGIN_EXTERN_C in this file, can I remove th=
e include? No, because other symbols from it might be used, even if they we=
ren't when the comment was written=2E

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=2E If so=
, concentrate on better naming, or better documentation of existing convent=
ions=2E
- Perhaps it is a justification added when the include was first added=2E =
If so, put it in the commit message and PR summary=2E

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=
=2E

--=20
Rowan Tommins
[IMSoP]
------1FJU0L4DTRCB3RZK8ZNOTVQFNC45R4--