Re: A question about wording in messages

From: Alvaro Herrera <alvherre(at)alvh(dot)no-ip(dot)org>
To: Kyotaro Horiguchi <horikyota(dot)ntt(at)gmail(dot)com>
Cc: tgl(at)sss(dot)pgh(dot)pa(dot)us, pgsql-hackers(at)lists(dot)postgresql(dot)org
Subject: Re: A question about wording in messages
Date: 2022-09-20 16:21:25
Message-ID: 20220920162125.gcngbhjuu7q3yr7d@alvherre.pgsql
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

On 2022-Sep-14, Kyotaro Horiguchi wrote:

> At Tue, 13 Sep 2022 22:38:46 -0400, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote in
> > Kyotaro Horiguchi <horikyota(dot)ntt(at)gmail(dot)com> writes:
> > > I saw the following message recently modified.
> > >> This controls the maximum distance we can read ahead in the WAL to prefetch referenced data blocks.
> > > Maybe the "we" means "PostgreSQL program and you" but I see it
> > > somewhat out of place.
> >
> > +1, I saw that today and thought it was outside our usual style.
> > The whole thing is awfully verbose for a GUC description, too.
> > Maybe
> >
> > "Maximum distance to read ahead in WAL to prefetch data blocks."

I failed to notice this issue. I agree it's unusual and +1 for changing it.

> It seems to sufficiently work for average users and rather easy to
> read, but it looks a short description.

> So, taking the middle of them, how about the following?
> Short: Buffer size for reading ahead in the WAL during recovery.
> Extra: This controls the maximum distance to read ahead in WAL to prefetch data blocks."

But why do we care that it's short? We don't need it to be long .. we
only need it to explain what it needs to explain.

After spending way too much time editing this line, I ended up with
exactly what Tom proposed, so +1 for his version. I think "This
controls" adds nothing very useful, and we don't have it anywhere else,
except tcp_keepalives_count from where I also propose to remove it.

Álvaro Herrera PostgreSQL Developer —
"Hay quien adquiere la mala costumbre de ser infeliz" (M. A. Evans)

Attachment Content-Type Size
0001-fix-some-GUC-strings.patch text/x-diff 1.4 KB

In response to


Browse pgsql-hackers by date

  From Date Subject
Next Message Zhihong Yu 2022-09-20 16:34:25 default sorting behavior for index
Previous Message Tom Lane 2022-09-20 16:15:13 Re: Tree-walker callbacks vs -Wdeprecated-non-prototype