Message-ID: <bc3da40a-3674-4633-a5ad-e1f610e8c0ef@paulmck-laptop>
Date: Sun, 11 Jan 2026 21:06:22 -0800
From: "Paul E. McKenney" <paulmck@...nel.org>
To: Steven Rostedt <rostedt@...dmis.org>
Cc: Theodore Tso <tytso@....edu>,
	"Dr. David Alan Gilbert" <dave@...blig.org>,
	Julia Lawall <julia.lawall@...ia.fr>,
	Sasha Levin <sashal@...nel.org>,
	Gabriele Paoloni <gpaoloni@...hat.com>,
	Kate Stewart <kstewart@...uxfoundation.org>,
	Chuck Wolber <chuckwolber@...il.com>,
	Dmitry Vyukov <dvyukov@...gle.com>,
	Mark Rutland <mark.rutland@....com>,
	Thomas Gleixner <tglx@...utronix.de>,
	Lorenzo Stoakes <lorenzo.stoakes@...cle.com>,
	Shuah Khan <skhan@...uxfoundation.org>, Chris Mason <clm@...a.com>,
	linux-kernel@...r.kernel.org
Subject: Re: Follow-up on Linux-kernel code accessibility

On Sun, Jan 11, 2026 at 12:11:51PM -0500, Steven Rostedt wrote:
> On Sat, 10 Jan 2026 19:30:40 -0800
> "Theodore Tso" <tytso@....edu> wrote:
> > 
> > Steven, you may disagree with this conclusion, but speaking
> > personally, everything that I've read on this thread strongly confirms
> > it.
> 
> I'm not talking about someone with no knowledge about the kernel. If
> someone has a strong understanding of how an operating system works,
> and a general idea of the system, looking at the comments in the code
> should be enough for them to figure out the understanding of what is
> happening.
> 
> I look at it as two levels. There's an architectural understanding
> (which is achieved via books and design documents and such) and then
> there's the implementation details. The implementation details should
> be expressed in comments, and actually avoided when possible from the
> design and architectural documentation. That's because the
> implementation can change, and does often.

You seem to be assuming that the implementation can always be understood
independent of the architecture.  This would be a brave assumption that
has not been borne out by my experience.

Or am I missing your point?

> > I am not sure that we can count on LLM's to provide reliable "active
> > software assistance", although a recent experiment, where I enabled
> > Gemini 3's "deep research" mode, and asked it the question, "How much
> > money do most software engineers need to retire?", resulted in a 15
> > page report[2], with footnotes, so you could verify whether or not the
> > LLM was halucinating or not --- and it was much better than I
> > expected.  I'm not sure I agree with all of it, but it's better than
> > many of the YouTube financial advice videos out there.  :-)
> > 
> > [2] https://docs.google.com/document/d/1EDqC-qnHkEyEeewXFx4PuL4VtnC_LxPZ2CKlleB7QBc/edit?tab=t.0
> 
> I fail to understand the analogy of using AI for financial security for
> retired software engineers and understanding an implementation of code
> by experience developers.
> 
> If I hit a bug that leads me to RCU code, I would hope there's enough
> commenting for me to understand if the bug is with RCU or my usage of
> RCU.

In this case, trawling through the RCU implementation itself would
not normally be the first choice.  I instead suggest starting
with the documentation of RCU's usage.  Documentation/RCU has a
lot of this, and there is also the 2024 edition of the RCU API:
https://lwn.net/Articles/988638.

There are of course always exceptions, but this is after all the purpose
of RCU's usage documentation.

> > Thta being said, there's a big difference between retirement planning
> > and trusting a LLM to be able to explain the finer points of say, an
> > I/O scheduler, the MM's OOM Killer hueristics, or RCU.  I suspect
> > there are no silver bullets here.
> 
> There was a performance issue that Joel pointed out which lead to this
> one function I was looking at. But with the use of various constants
> that don't appear to be documented anywhere made it impossible for me
> to know if that code really was the performance issue or not. Sure I
> could simply ask Paul or Joel why is 3 so important here, but the fact
> I need to ask is a fail in my mind.

Failure or not, in this particular case, again, please reach out to
Joel while CCing rcu@...r.kernel.org.  And again, the current state of
RCU commenting is somewhere between "notes to Paul" and sufficient for
those working closely with it.

And again, I do not expect RCU's commenting to support context free
dives into random places in its code any time soon.

> I have the same issue with the scheduler. There's parts of the
> scheduler that I worked on years ago, but the changes to it, I have no
> idea why it's doing what it is doing because there's no comments about
> it. The design is basically the same, but the implementation has
> changed. I'm going to be actively fixing that, as one of my OKRs is to
> comment the scheduler in more detail as to explain why functions do
> what they do.

A few weeks back, I took the liberty of doing a quick scan through the
kernel for use of constants, and there are a *lot* of them.  The scheduler
and RCU are among the least of the problems.  And at least some of the
scheduler's use of constants look to be in code implementing digital
filters of one sort or another.  Such constants tend to be empirical in
nature, and the reason for the choice is usually "because this particular
value works better than the other choices".

But I do applaud your going through the scheduler to improve comments.
Going through RCU with Boqun, Frederic, Joel, Neeraj, and Uladzislau
certainly greatly improved RCU's comments, inadequate though you
apparently consider them to be.  And so, as I mentioned earlier, I would
be happy to participate in another walkthrough.  ;-)

							Thanx, Paul

Powered by blists - more mailing lists