Re: [PATCH v2] Documentation: remove magic number doc

From: Bagas Sanjaya <bagasdotme@gmail.com>
To: наб <nabijaczleweli@nabijaczleweli.xyz>
Cc: Jonathan Corbet <corbet@lwn.net>,
	Federico Vaga <federico.vaga@vaga.pv.it>,
	Alex Shi <alexs@kernel.org>, Yanteng Si <siyanteng@loongson.cn>,
	Hu Haowen <src.res@email.cn>,
	Thomas Gleixner <tglx@linutronix.de>,
	linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
	linux-doc-tw-discuss@lists.sourceforge.net
Subject: Re: [PATCH v2] Documentation: remove magic number doc
Date: Wed, 14 Sep 2022 09:22:28 +0700	[thread overview]
Message-ID: <731a3b01-1ade-6003-eb21-6b0a2c919750@gmail.com> (raw)
In-Reply-To: <20220907231109.htnfxzmr6wkuhn2v@tarta.nabijaczleweli.xyz>

On 9/8/22 06:11, наб wrote:
> The entire file blames back to the start of git
> (minus whitespace from the RST translation and a typo fix):
>   * there are changelog comments for March 1994 through to Linux 2.5.74
>   * struct tty_ldisc is two pointers nowadays, so naturally no magic
>   * GDA_MAGIC is defined but unused, and it's been this way
>     since start-of-git
>   * M3_CARD_MAGIC isn't defined, because
>     commit d56b9b9c464a10ab1ee51a4c6190a2b57b8ef7a6 ("[PATCH] The
>     scheduled removal of some OSS drivers")
>     removed the entire driver in 2006
>   * CS_CARD_MAGIC likewise since
>     commit b5d425c97f7d4e92151167b01ca038e7853c6b37 ("more scheduled OSS
>     driver removal") in 2007
>   * KMALLOC_MAGIC and VMALLOC_MAGIC were removed in
>     commit e38e0cfa48ac38f4fe24453d2523852467c95b21 ("[ALSA] Remove
>     kmalloc wrappers"), six months after start of git
>   * SLAB_C_MAGIC has never even appeared in git
>     (removed in in 2.4.0-test3pre6)
>

Hi,

The patch description can be improved, see below.

Nit: Use abbreviated hash when referring to commits (`git show -s
--pretty=format:"%h (\"%s\")`). You may need to set `core.abbrev=12`
in your `~/.gitconfig`.

> At a glance, the only ones still in use are in code mostly untouched
> since git (TTY, SLIP, SCSI (drivers/scsi/{arm/queue.c,ncr53c8xx.c}),
> &c., but not PPP or PTY (neither exist now)).
>

"... are in drivers which are mostly untouched..."

Also, really PPP and PTY have been burninated? Since what commit?

> A rough estimate of magic numbers in the kernel may be obtained via
>   # git grep define | grep '_MAGIC\b' |
>     grep -ve IOC  -e ^tools/ -e '_IO[(WR]' -e _SUPER | wc -l
>   780
> there is, of course, a few other meanings of magic here,
> but a random sampling of SR_EEPROM_MAGIC, L2TP_TUNNEL_MAGIC,
> and MD_SB_MAGIC showed they are all used like magic-number.rst describes
> and are not in it
> 

"A rough estimate ... is obtained by:"

"Note that the word 'magic' may have different meaning from magic
number context.
There are also magic numbers which aren't listed here, like ..."

> By all accounts, it seems magic-number.rst is a low-value historical
> relic at best and misleading cruft at worst
> 

"Therefore, magic-number.rst is a low-value historial relic at best and
misleading cruft at worst, so remove the documentation."

Thanks.

-- 
An old man doll... just what I always wanted! - Clara