Regards, On 18 January 2023 16:07:52 GMT, Max Kellermann <max+...@blarg.de> wrote: >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]
