Re: Follow-up on Linux-kernel code accessibility

["Dr. David Alan Gilbert" <dave@treblig.org>]

* 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 <julia.lawall@inria.fr> 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   |_______/