From f667717f73a544c916785cae480f62cf7c925946 Mon Sep 17 00:00:00 2001 From: Max Kellermann Date: Mon, 30 Jan 2023 10:39:01 +0100 Subject: [PATCH] remove #include comments Several PHP maintainers have argued that code comments explaining include directives are bad. - @dstogov wrote "It adds almost useless comments that are not goigg to be kept as to date" https://marc.info/?l=php-internals&m=167403155727727&w=2 - @derickr wrote "Adding comments that go out of date as to why a header is included is also clutter." https://marc.info/?l=php-internals&m=167405646312575&w=2 - @kamil-tekiela wrote "I am against putting comments on #includes. Comments are noise in code and often go out of date." https://marc.info/?l=php-internals&m=167406432218721&w=2 I don't agree with them; I believe that code comments help others understand and maintain the code. Of course, like any code comment, they become obsolete and wrong, but outdated comments are still better than no comment at all. With this argument, you can easily say that nobody should ever write a code comment. My RFC https://wiki.php.net/rfc/include_cleanup contains a vote on whether #includes are allowed to have explanatory code comments; if this is denied, then please merge this PR to get rid of many existing comments which my work has imitated. --- ext/fileinfo/fileinfo.c | 4 ++-- ext/hash/murmur/PMurHash.c | 2 +- ext/hash/murmur/PMurHash128.c | 2 +- ext/hash/xxhash/xxhash.h | 6 +++--- ext/mbstring/php_mbregex.c | 2 +- ext/mysqlnd/config-win.h | 2 +- ext/opcache/jit/vtune/ittnotify_config.h | 2 +- ext/sockets/conversions.c | 2 +- ext/sockets/sockaddr_conv.h | 2 +- ext/sockets/windows_common.h | 2 +- ext/standard/formatted_print.c | 2 +- ext/standard/info.c | 2 +- ext/standard/php_http.h | 2 +- main/reentrancy.c | 2 +- main/streams/streams.c | 4 ++-- sapi/cli/php_cli_server.c | 8 ++++---- sapi/cli/ps_title.c | 4 ++-- sapi/fpm/fpm/fpm.c | 2 +- sapi/fpm/fpm/fpm_clock.c | 2 +- sapi/fpm/fpm/fpm_events.c | 2 +- sapi/fpm/fpm/fpm_php.h | 2 +- sapi/fpm/fpm/fpm_sockets.c | 2 +- win32/sendmail.c | 2 +- win32/wsyslog.c | 2 +- 24 files changed, 32 insertions(+), 32 deletions(-) diff --git a/ext/fileinfo/fileinfo.c b/ext/fileinfo/fileinfo.c index a6f3e64db6b45..51ed02944d4c1 100644 --- a/ext/fileinfo/fileinfo.c +++ b/ext/fileinfo/fileinfo.c @@ -27,10 +27,10 @@ #include "php_ini.h" #include "ext/standard/info.h" -#include "ext/standard/file.h" /* needed for context stuff */ +#include "ext/standard/file.h" #include "php_fileinfo.h" #include "fileinfo_arginfo.h" -#include "fopen_wrappers.h" /* needed for is_url */ +#include "fopen_wrappers.h" #include "Zend/zend_exceptions.h" /* {{{ macros and type definitions */ diff --git a/ext/hash/murmur/PMurHash.c b/ext/hash/murmur/PMurHash.c index 0716ca13c88ff..f43ecfdb246cb 100644 --- a/ext/hash/murmur/PMurHash.c +++ b/ext/hash/murmur/PMurHash.c @@ -70,7 +70,7 @@ on big endian machines, or a byte-by-byte read if the endianess is unknown. /* Find best way to ROTL */ #if defined(_MSC_VER) #define FORCE_INLINE static __forceinline - #include /* Microsoft put _rotl declaration in here */ + #include #define ROTL32(x,y) _rotl(x,y) #else #define FORCE_INLINE static inline __attribute__((always_inline)) diff --git a/ext/hash/murmur/PMurHash128.c b/ext/hash/murmur/PMurHash128.c index 4425f81575ef8..b8e81695117ae 100644 --- a/ext/hash/murmur/PMurHash128.c +++ b/ext/hash/murmur/PMurHash128.c @@ -62,7 +62,7 @@ on big endian machines. /* Find best way to ROTL */ #if defined(_MSC_VER) #define FORCE_INLINE static __forceinline - #include /* Microsoft put _rotl declaration in here */ + #include #define ROTL32(x,y) _rotl(x,y) #define ROTL64(x,y) _rotl64(x,y) #define BIG_CONSTANT(x) (x) diff --git a/ext/hash/xxhash/xxhash.h b/ext/hash/xxhash/xxhash.h index 7850622aae44a..4b8c2dbb26911 100644 --- a/ext/hash/xxhash/xxhash.h +++ b/ext/hash/xxhash/xxhash.h @@ -339,7 +339,7 @@ XXH_PUBLIC_API unsigned XXH_versionNumber (void); /* **************************** * Common basic types ******************************/ -#include /* size_t */ +#include typedef enum { XXH_OK=0, XXH_ERROR } XXH_errorcode; @@ -1482,7 +1482,7 @@ static void* XXH_memcpy(void* dest, const void* src, size_t size) return memcpy(dest,src,size); } -#include /* ULLONG_MAX */ +#include /* ************************************* @@ -5445,7 +5445,7 @@ XXH_PUBLIC_API XXH128_hash_t XXH3_128bits_digest (const XXH3_state_t* state) /* 128-bit utility functions */ -#include /* memcmp, memcpy */ +#include /* return : 1 is equal, 0 if different */ /*! @ingroup xxh3_family */ diff --git a/ext/mbstring/php_mbregex.c b/ext/mbstring/php_mbregex.c index 99dc91e34dcae..106e0d6bd2050 100644 --- a/ext/mbstring/php_mbregex.c +++ b/ext/mbstring/php_mbregex.c @@ -27,7 +27,7 @@ #include "mbstring.h" #include "libmbfl/filters/mbfilter_utf8.h" -#include "php_onig_compat.h" /* must come prior to the oniguruma header */ +#include "php_onig_compat.h" #include #undef UChar diff --git a/ext/mysqlnd/config-win.h b/ext/mysqlnd/config-win.h index 73a732fa76617..6b2c6f2a66be8 100644 --- a/ext/mysqlnd/config-win.h +++ b/ext/mysqlnd/config-win.h @@ -8,7 +8,7 @@ This file is public domain and comes with NO WARRANTY of any kind */ #include #include -#include /* Because of rint() */ +#include #include #include #include diff --git a/ext/opcache/jit/vtune/ittnotify_config.h b/ext/opcache/jit/vtune/ittnotify_config.h index fc3a476cdd1c9..980384bb069ac 100644 --- a/ext/opcache/jit/vtune/ittnotify_config.h +++ b/ext/opcache/jit/vtune/ittnotify_config.h @@ -395,7 +395,7 @@ typedef struct ___itt_thread_info struct ___itt_thread_info* next; } __itt_thread_info; -#include "ittnotify_types.h" /* For __itt_group_id definition */ +#include "ittnotify_types.h" typedef struct ___itt_api_info_20101001 { diff --git a/ext/sockets/conversions.c b/ext/sockets/conversions.c index ae90cbe59d2a7..866cfd34db57b 100644 --- a/ext/sockets/conversions.c +++ b/ext/sockets/conversions.c @@ -4,7 +4,7 @@ #endif #include "sockaddr_conv.h" #include "conversions.h" -#include "sendrecvmsg.h" /* for ancillary registry */ +#include "sendrecvmsg.h" #ifdef PHP_WIN32 # include "windows_common.h" #endif diff --git a/ext/sockets/sockaddr_conv.h b/ext/sockets/sockaddr_conv.h index 1e7e3cf046d0a..7269be106ccf3 100644 --- a/ext/sockets/sockaddr_conv.h +++ b/ext/sockets/sockaddr_conv.h @@ -2,7 +2,7 @@ #define PHP_SOCKADR_CONV_H #include -#include "php_sockets.h" /* php_socket */ +#include "php_sockets.h" #ifndef PHP_WIN32 # include diff --git a/ext/sockets/windows_common.h b/ext/sockets/windows_common.h index 0b8cdfe2e5d93..251ed12e80d8f 100644 --- a/ext/sockets/windows_common.h +++ b/ext/sockets/windows_common.h @@ -16,7 +16,7 @@ #include #define NTDDI_XP NTDDI_WINXP /* bug in SDK */ -#include /* conflicting definition of CMSG_DATA */ +#include #undef NTDDI_XP #define HAVE_IF_NAMETOINDEX 1 diff --git a/ext/standard/formatted_print.c b/ext/standard/formatted_print.c index b988422df21ca..4348ff1cd6aca 100644 --- a/ext/standard/formatted_print.c +++ b/ext/standard/formatted_print.c @@ -14,7 +14,7 @@ +----------------------------------------------------------------------+ */ -#include /* modf() */ +#include #include "php.h" #include "ext/standard/head.h" #include "php_string.h" diff --git a/ext/standard/info.c b/ext/standard/info.c index 0c4081d2a9151..f8f3911e03848 100644 --- a/ext/standard/info.c +++ b/ext/standard/info.c @@ -27,7 +27,7 @@ #include "SAPI.h" #include #include "php_main.h" -#include "zend_globals.h" /* needs ELS */ +#include "zend_globals.h" #include "zend_extensions.h" #include "zend_highlight.h" #ifdef HAVE_SYS_UTSNAME_H diff --git a/ext/standard/php_http.h b/ext/standard/php_http.h index 9350be597ea1c..225a560bfa8f4 100644 --- a/ext/standard/php_http.h +++ b/ext/standard/php_http.h @@ -18,7 +18,7 @@ #define PHP_HTTP_H #include "php.h" -#include "zend_types.h" /* for zend_string */ +#include "zend_types.h" #include "zend_smart_str.h" PHPAPI void php_url_encode_hash_ex(HashTable *ht, smart_str *formstr, diff --git a/main/reentrancy.c b/main/reentrancy.c index 6d39a4ebd873d..f987dd38360a2 100644 --- a/main/reentrancy.c +++ b/main/reentrancy.c @@ -22,7 +22,7 @@ #endif #include "php_reentrancy.h" -#include "ext/random/php_random.h" /* for PHP_RAND_MAX */ +#include "ext/random/php_random.h" enum { LOCALTIME_R, diff --git a/main/streams/streams.c b/main/streams/streams.c index 1231dbebd63ae..02dd2949fb578 100644 --- a/main/streams/streams.c +++ b/main/streams/streams.c @@ -26,8 +26,8 @@ #include "php_network.h" #include "php_open_temporary_file.h" #include "ext/standard/file.h" -#include "ext/standard/basic_functions.h" /* for BG(CurrentStatFile) */ -#include "ext/standard/php_string.h" /* for php_memnstr, used by php_stream_get_record() */ +#include "ext/standard/basic_functions.h" +#include "ext/standard/php_string.h" #include #include #include "php_streams_int.h" diff --git a/sapi/cli/php_cli_server.c b/sapi/cli/php_cli_server.c index 901281ddfdfca..e4611433a2a99 100644 --- a/sapi/cli/php_cli_server.c +++ b/sapi/cli/php_cli_server.c @@ -90,12 +90,12 @@ # define SOCK_EADDRINUSE WSAEADDRINUSE #endif -#include "ext/standard/file.h" /* for php_set_sock_blocking() :-( */ +#include "ext/standard/file.h" #include "zend_smart_str.h" #include "ext/standard/html.h" -#include "ext/standard/url.h" /* for php_raw_url_decode() */ -#include "ext/standard/php_string.h" /* for php_dirname() */ -#include "ext/date/php_date.h" /* for php_format_date() */ +#include "ext/standard/url.h" +#include "ext/standard/php_string.h" +#include "ext/date/php_date.h" #include "php_network.h" #include "php_http_parser.h" diff --git a/sapi/cli/ps_title.c b/sapi/cli/ps_title.c index a5a16f2dea125..919b71c3f5eff 100644 --- a/sapi/cli/ps_title.c +++ b/sapi/cli/ps_title.c @@ -51,10 +51,10 @@ extern char** environ; #include #ifdef HAVE_SYS_PSTAT_H -#include /* for HP-UX */ +#include #endif #ifdef HAVE_PS_STRINGS -#include /* for old BSD */ +#include #include #endif #if defined(DARWIN) diff --git a/sapi/fpm/fpm/fpm.c b/sapi/fpm/fpm/fpm.c index cb86f403b89c9..ee12ed8aa7adb 100644 --- a/sapi/fpm/fpm/fpm.c +++ b/sapi/fpm/fpm/fpm.c @@ -2,7 +2,7 @@ #include "fpm_config.h" -#include /* for exit */ +#include #include "fpm.h" #include "fpm_children.h" diff --git a/sapi/fpm/fpm/fpm_clock.c b/sapi/fpm/fpm/fpm_clock.c index 57faccbe9d80d..78d51773e5bbc 100644 --- a/sapi/fpm/fpm/fpm_clock.c +++ b/sapi/fpm/fpm/fpm_clock.c @@ -3,7 +3,7 @@ #include "fpm_config.h" #ifdef HAVE_CLOCK_GETTIME -#include /* for CLOCK_MONOTONIC */ +#include #endif #include "fpm_clock.h" diff --git a/sapi/fpm/fpm/fpm_events.c b/sapi/fpm/fpm/fpm_events.c index 4cc56067bfc6c..01c73b7bf3109 100644 --- a/sapi/fpm/fpm/fpm_events.c +++ b/sapi/fpm/fpm/fpm_events.c @@ -4,7 +4,7 @@ #include #include -#include /* for putenv */ +#include #include #include diff --git a/sapi/fpm/fpm/fpm_php.h b/sapi/fpm/fpm/fpm_php.h index 01ed65799170d..975e09db5df1c 100644 --- a/sapi/fpm/fpm/fpm_php.h +++ b/sapi/fpm/fpm/fpm_php.h @@ -6,7 +6,7 @@ #include #include "php.h" -#include "build-defs.h" /* for PHP_ defines */ +#include "build-defs.h" #include "fpm/fpm_conf.h" #define FPM_PHP_INI_TO_EXPAND \ diff --git a/sapi/fpm/fpm/fpm_sockets.c b/sapi/fpm/fpm/fpm_sockets.c index 66488b9bf000e..fce75114c6244 100644 --- a/sapi/fpm/fpm/fpm_sockets.c +++ b/sapi/fpm/fpm/fpm_sockets.c @@ -6,7 +6,7 @@ #include #endif #include -#include /* for chmod(2) */ +#include #include #include #include diff --git a/win32/sendmail.c b/win32/sendmail.c index 6263eaac1a094..7b62702299689 100644 --- a/win32/sendmail.c +++ b/win32/sendmail.c @@ -17,7 +17,7 @@ * */ -#include "php.h" /*php specific */ +#include "php.h" #include #include #include diff --git a/win32/wsyslog.c b/win32/wsyslog.c index b4e58b15629a7..a742525a5e65b 100644 --- a/win32/wsyslog.c +++ b/win32/wsyslog.c @@ -50,7 +50,7 @@ * Lift a leg, Yunie. Luv ya forever!!!! */ -#include "php.h" /*php specific */ +#include "php.h" #include "syslog.h" #include #include