From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mx.treblig.org (mx.treblig.org [46.235.229.95]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 58A25220F49 for ; Mon, 29 Dec 2025 17:02:21 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=46.235.229.95 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1767027743; cv=none; b=pvjxfqdonqX5qqFxBsdou1a4DRUkkLYCtUzrELuzZW+cVnBnYbCrKWSj1ww+SR5InQmq8xSSPEXCkE7T0lkuUoMEnpU3vhZtswnerA/jD0wn8r+JAe25tuMe37JxptWCfFSfXsmQZxri01nF/SEWMcGshtJb6SEyBasfjmKt6kU= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1767027743; c=relaxed/simple; bh=fk5xZppsVCUIRiMcGtrjnSzRhI+dyQ/qaDJw77CaZuY=; h=Date:From:To:Cc:Subject:Message-ID:References:MIME-Version: Content-Type:Content-Disposition:In-Reply-To; b=dODb/tssvBYqyuKtSSwdCteMdrJBXUwnfV3AebEJoT0YyNqlzMpQojpj9xvy/tk7nrDStvaL06l1JegxSL0H9UjYlsxIMFgIBdHgv1cQVffH0iKFvrImkv7fMyhPD49e6SC7cS10Io3vuI8Q44n9iZqIfDBIPxqecO399+yOfE8= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=treblig.org; spf=pass smtp.mailfrom=treblig.org; dkim=pass (2048-bit key) header.d=treblig.org header.i=@treblig.org header.b=H5TbJZ8J; arc=none smtp.client-ip=46.235.229.95 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=treblig.org Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=treblig.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=treblig.org header.i=@treblig.org header.b="H5TbJZ8J" DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=treblig.org ; s=bytemarkmx; h=Content-Type:MIME-Version:Message-ID:Subject:From:Date:From :Subject; bh=4FFsO4BhJp6HG2WY+nYp9MfB9cgoIr16ewCY4diAXhg=; b=H5TbJZ8JCTqWdAvG 8XAhdrzo7FkRmPkaOMXqi3CnTnWWMFuJqBjT/km+bzbJVWzMu30B36JKot86p5dCo2zhRwU277dq9 iUQdTSWtqOZ/vaWXa1+HuvzBhptImCnnID5FWpvVy8rSewvrzZwpIXDJApoGO3f/ldnSE8YB55Veo kcJx69JKVQsPxE2mbGSrjFSOCXeM+wMAVKWjP5LykAOtfA1irV3AI7ilAyogjEXq8hkFS0EXaSjNr VOZK5cS5AtA1dEwJqIwPyQWrMeE8hFkwgQke+6dk4mjrAKVvyEF6xr7/upPZUN/eUBUwG7HzMPfTD UdSGDorcjedB5Usk1A==; Received: from dg by mx.treblig.org with local (Exim 4.98.2) (envelope-from ) id 1vaGdA-0000000Bcf0-2pIe; Mon, 29 Dec 2025 17:02:04 +0000 Date: Mon, 29 Dec 2025 17:02:04 +0000 From: "Dr. David Alan Gilbert" To: "Paul E. McKenney" Cc: Steven Rostedt , Julia Lawall , Theodore Tso , Sasha Levin , Gabriele Paoloni , Kate Stewart , Chuck Wolber , Dmitry Vyukov , Mark Rutland , Thomas Gleixner , Lorenzo Stoakes , Shuah Khan , Chris Mason , linux-kernel@vger.kernel.org Subject: Re: Follow-up on Linux-kernel code accessibility Message-ID: References: <6915da9a-6cd7-c2a9-776d-963949a413c@inria.fr> <8005c35a-d8dc-4908-93e5-46bd206f0139@paulmck-laptop> <435c7085-34e-16e9-5711-e53aa54cf4fc@inria.fr> <20251229104005.18b25def@gandalf.local.home> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Disposition: inline In-Reply-To: X-Chocolate: 70 percent or better cocoa solids preferably X-Operating-System: Linux/6.12.48+deb13-amd64 (x86_64) X-Uptime: 16:52:55 up 63 days, 16:29, 2 users, load average: 0.00, 0.00, 0.00 User-Agent: Mutt/2.2.13 (2024-03-09) * Paul E. McKenney (paulmck@kernel.org) wrote: > On Mon, Dec 29, 2025 at 10:40:05AM -0500, Steven Rostedt wrote: > > On Sun, 28 Dec 2025 10:36:39 +0100 (CET) > > Julia Lawall wrote: > > > > > > > > > j = (j + 2) / 3; > > > > > > > > > > > > "Divide by three rounding up." > > > > That's as useful as: > > > > /* Add one to X */ > > x++; > > > > > > > > > > > > That's not *that* obvious, but ok, but then why 3? > > > > > > > > > Bingo! You win a cigar! :-) > > > > I know that was a round up (and yes, as David pointed out, we have macros > > for that too). The question is why are you dividing it by 3? I don't see > > anything in that function which suggests the reason for needing to divide j > > by 3. > > > > If the comments you were adding in the past was things like "Divide by > > three rounding up" then yeah, I can see why people would say you have too > > many comments. The comments are not to be discussing what is being done, > > but why is it being done. > > > > WRITE_ONCE(rcu_state.jiffies_kick_kthreads, > > jiffies + (j ? 3 * j : 2)); > > > > > > Why the: (j ? 3 * j : 2) ? > > > > Why is 3 so magical? > > > > /* > > * j is the Father, Son and Holy Ghost. > > * But only one may be active at a time. > > * They each take a third. Father is first, > > * Son is second, and Holy Ghost is third. > > */ > > j = (j + 2) / 3; > > > > /* > > * j may not be zero, as that would lead to > > * damnation. > > */ > > if (j <= 0) > > j = 1; > > I would of course nack that comment, amusing though it might be to track > others' reactions to it over time. ;-) > > So you are now unwilling to do a walkthrough? That would be unfortunate. > > If your view is that I should just answer the question so that > everyone can get on with life, please keep in mind that there are some > tens of thousands of other lines of code in Linux-kernel RCU. It is > therefore only reasonable that I insist upon a more organized approach. I'm actually not interested in the answer to what the magical 3 is *; I just think this piece of code is a nice example of code that has poor accessibility - both for human and AI - although frankly the humans might find it harder. My point of my previous response was that I don't think this is an example of something that needs clever extra stuff for some of the accessibility issues; just the basics of not using magic constants and making sure clever tricks are either commented or use appropriate named functions. That's just basic good style! > In addition, as noted earlier [1], you guys are members of one of the > smaller audiences that need my assistance. Plus you were on CC for the > patch that added this line. ;-) > > On the other hand, if your view is instead that because the three of > you don't immediately grok this line of code, I should be willing to > take hundreds of lines of LLM-generated comments for each and every > non-trivial RCU function (for some TBD definition of "non-trivial"), > sorry, but no, that does not follow. That indeed would be terrible; but a few clear basic comments around clever stuff would be great. Dave (* It's obviously for Huey, Dewey, and Louie) > Thanx, Paul > > [1] https://lore.kernel.org/all/fe8c7e28-b5fe-4411-b27c-b2efd89a74c7@paulmck-laptop/ -- -----Open up your eyes, open up your mind, open up your code ------- / Dr. David Alan Gilbert | Running GNU/Linux | Happy \ \ dave @ treblig.org | | In Hex / \ _________________________|_____ http://www.treblig.org |_______/