Horton

Thread

Commits

  1. Clarify some comments making use of leetspeak term "up2date"

  2. doc: restore intentional typo

  3. Introduce logical decoding.

  1. Replace l337sp34k in comments.

    Peter Smith <smithpb2250@gmail.com> — 2021-07-27T23:39:02Z

    IMO the PG code comments are not an appropriate place for leetspeak creativity.

PSA a patch to replace a few examples that I recently noticed.

"up2date" --> "up-to-date"

------
Kind Regards,
Peter Smith.
Fujitsu Australia

  2. Re: Replace l337sp34k in comments.

    Michael Paquier <michael@paquier.xyz> — 2021-07-28T01:32:25Z

    On Wed, Jul 28, 2021 at 09:39:02AM +1000, Peter Smith wrote:
> IMO the PG code comments are not an appropriate place for leetspeak creativity.
> 
> PSA a patch to replace a few examples that I recently noticed.
> 
> "up2date" --> "up-to-date"

Agreed that this is a bit cleaner to read, so done.  Just note that
pgindent has been complaining about the format of some of the updated
comments.
--
Michael

  3. Re: Replace l337sp34k in comments.

    Peter Smith <smithpb2250@gmail.com> — 2021-07-28T23:08:23Z

    On Wed, Jul 28, 2021 at 11:32 AM Michael Paquier <michael@paquier.xyz> wrote:
>
> On Wed, Jul 28, 2021 at 09:39:02AM +1000, Peter Smith wrote:
> > IMO the PG code comments are not an appropriate place for leetspeak creativity.
> >
> > PSA a patch to replace a few examples that I recently noticed.
> >
> > "up2date" --> "up-to-date"
>
> Agreed that this is a bit cleaner to read, so done.  Just note that
> pgindent has been complaining about the format of some of the updated
> comments.

Thanks for pushing!

BTW, the commit comment [1] attributes most of these to a recent
patch, but I think that is mistaken.  AFAIK they are from when the
file was first introduced 8 years ago [2].

------
[1] https://github.com/postgres/postgres/commit/7b7fbe1e8bb4b2a244d1faa618789db411316e55
[2] https://github.com/postgres/postgres/commit/b89e151054a05f0f6d356ca52e3b725dd0505e53#diff-034b6d4eaf36425e75d7a7087d09bd6c734dd9ea8398533559d537d13b6b9197

Kind Regards,
Peter Smith.
Fujitsu Australia

  4. Re: Replace l337sp34k in comments.

    Andrew Dunstan <andrew@dunslane.net> — 2021-07-29T10:22:57Z

    On 7/27/21 7:39 PM, Peter Smith wrote:
> IMO the PG code comments are not an appropriate place for leetspeak creativity.
>
> PSA a patch to replace a few examples that I recently noticed.
>
> "up2date" --> "up-to-date"
>

Personally, I would have written this as just "up to date", I don't
think the hyphens are required.


cheers


andrew


--
Andrew Dunstan
EDB: https://www.enterprisedb.com

  5. Re: Replace l337sp34k in comments.

    Geoff Winkless <pgsqladmin@geoff.dj> — 2021-07-29T12:51:36Z

    On Thu, 29 Jul 2021 at 11:22, Andrew Dunstan <andrew@dunslane.net> wrote:

> Personally, I would have written this as just "up to date", I don't
> think the hyphens are required.
>

FWIW Mirriam-Webster and the CED suggest "up-to-date" when before a noun,
so the changes should be "up-to-date answer" but "are up to date".

https://dictionary.cambridge.org/dictionary/english/up-to-date

Geoff

  6. Re: Replace l337sp34k in comments.

    Andrew Dunstan <andrew@dunslane.net> — 2021-07-29T15:11:57Z

    On 7/29/21 8:51 AM, Geoff Winkless wrote:
> On Thu, 29 Jul 2021 at 11:22, Andrew Dunstan <andrew@dunslane.net
> <mailto:andrew@dunslane.net>> wrote:
>
>     Personally, I would have written this as just "up to date", I don't
>     think the hyphens are required.
>
>  
> FWIW Mirriam-Webster and the CED suggest "up-to-date" when before a
> noun, so the changes should be "up-to-date answer" but "are up to date".
>
> https://dictionary.cambridge.org/dictionary/english/up-to-date
> <https://dictionary.cambridge.org/dictionary/english/up-to-date>
>
>

Interesting, thanks. My (admittedly old) Concise OED only has the
version with spaces, while my (also old) Collins Concise has the
hyphenated version. I learn something new every day, no matter how trivial.


cheers


andrew

--
Andrew Dunstan
EDB: https://www.enterprisedb.com

  7. Re: Replace l337sp34k in comments.

    Gavin Flower <gavinflower@archidevsys.co.nz> — 2021-07-29T21:46:59Z

    On 30/07/21 12:51 am, Geoff Winkless wrote:
> On Thu, 29 Jul 2021 at 11:22, Andrew Dunstan <andrew@dunslane.net 
> <mailto:andrew@dunslane.net>> wrote:
>
>     Personally, I would have written this as just "up to date", I don't
>     think the hyphens are required.
>
> FWIW Mirriam-Webster and the CED suggest "up-to-date" when before a 
> noun, so the changes should be "up-to-date answer" but "are up to date".
>
> https://dictionary.cambridge.org/dictionary/english/up-to-date 
> <https://dictionary.cambridge.org/dictionary/english/up-to-date>
>
> Geoff

That 'feels' right to me.

Though in code, possibly it would be better to just use 'up-to-date' in 
code for consistency and to make the it easier to grep?

As a minor aside: double quotes should be used for speech and single 
quotes for quoting!


Cheers,
Gavin

  8. Re: Replace l337sp34k in comments.

    Michael Paquier <michael@paquier.xyz> — 2021-07-30T00:48:47Z

    On Fri, Jul 30, 2021 at 09:46:59AM +1200, Gavin Flower wrote:
> That 'feels' right to me.
> 
> Though in code, possibly it would be better to just use 'up-to-date' in code
> for consistency and to make the it easier to grep?

The change in llvmjit_expr.c may not look like an adjective though,
which I admit can be a bit confusing.  Still that does not look
completely wrong to me either.
--
Michael

  9. Re: Replace l337sp34k in comments.

    Geoff Winkless <pgsqladmin@geoff.dj> — 2021-07-30T08:05:53Z

    On Thu, 29 Jul 2021 at 22:46, Gavin Flower
<GavinFlower@archidevsys.co.nz> wrote:
> Though in code, possibly it would be better to just use 'up-to-date' in
> code for consistency and to make the it easier to grep?

If it's causing an issue, perhaps using a less syntactically
problematic synonym like "current" might be better?

:)

Geoff

  10. Re: Replace l337sp34k in comments.

    Gavin Flower <gavinflower@archidevsys.co.nz> — 2021-07-30T21:15:59Z

    On 30/07/21 8:05 pm, Geoff Winkless wrote:
> On Thu, 29 Jul 2021 at 22:46, Gavin Flower
> <GavinFlower@archidevsys.co.nz> wrote:
>> Though in code, possibly it would be better to just use 'up-to-date' in
>> code for consistency and to make the it easier to grep?
> If it's causing an issue, perhaps using a less syntactically
> problematic synonym like "current" might be better?
>
> :)
>
> Geoff

On thinking further...

The word 'current' means different things in different contexts. If I 
refer to my current O/S it means the one I'm using now, but it may not 
be current.  The second use of 'current' is the meaning you are thinking 
of, but the first is not. Since people reading documented code are 
focused on understanding technical aspects, they may miss this subtlety.

I'm aware that standardisation may meet with some resistance, but being 
consistent might reduce the conceptual impedance when reading the code.  
I'm just trying to reduce the potential for confusion.


Cheers,
Gavin

  11. Re: Replace l337sp34k in comments.

    x4mmm@yandex-team.ru — 2021-07-31T08:21:58Z

    
> 28 июля 2021 г., в 04:39, Peter Smith <smithpb2250@gmail.com> написал(а):
> 
> IMO the PG code comments are not an appropriate place for leetspeak creativity.
> 
> PSA a patch to replace a few examples that I recently noticed.
> 
> "up2date" --> "up-to-date"

FWIW, my 2 cents.
I do not see much difference between up2date, up-to-date, up to date, current, recent, actual, last, newest, correct, fresh etc.
I'm slightly leaning to 1337 version, but this can totally be ignored.

As a non-native speaker I'm a bit concerned by the fact that comment is copied 6 times. For me it's not a single bit easier to read comment then code. If this comment is that important, maybe refactor this assignment into function and document once?

Thanks!

Best regards, Andrey Borodin.

  12. Re: Replace l337sp34k in comments.

    Peter Geoghegan <pg@bowt.ie> — 2021-07-31T09:15:34Z

    On Sat, Jul 31, 2021 at 11:22 AM Andrey Borodin <x4mmm@yandex-team.ru> wrote:
> FWIW, my 2 cents.
> I do not see much difference between up2date, up-to-date, up to date, current, recent, actual, last, newest, correct, fresh etc.

+1.

To me it seems normal to debate wording/terminology with new code
comments, but that's about it. I find this zeal to change old code
comments misguided. It's okay if they're clearly wrong or have typos.
Anything else is just hypercorrection. And in any case there is a very
real chance of making the overall situation worse rather than better.
Probably in some subtle but important way.

See also: commit 8a47b775a16fb4f1e154c0f319a030498e123164

-- 
Peter Geoghegan

  13. Re: Replace l337sp34k in comments.

    David G. Johnston <david.g.johnston@gmail.com> — 2021-07-31T15:04:40Z

    On Saturday, July 31, 2021, Peter Geoghegan <pg@bowt.ie> wrote:

> On Sat, Jul 31, 2021 at 11:22 AM Andrey Borodin <x4mmm@yandex-team.ru>
> wrote:
> > FWIW, my 2 cents.
> > I do not see much difference between up2date, up-to-date, up to date,
> current, recent, actual, last, newest, correct, fresh etc.
>
> +1.
>
> To me it seems normal to debate wording/terminology with new code
> comments, but that's about it. I find this zeal to change old code
> comments misguided.
>

Maybe in general I would agree but I agree that this warrants an
exception.  While maybe not explicitly stated the use of up2date as a term
is against the de-facto style guide for our project and should be corrected
regardless of how long it took to discover the violation.  We fix other
unimportant but obvious typos all the time and this is no different.  We
don’t ask people to police this but we also don’t turn down well-written
patches.

David J.

  14. Re: Replace l337sp34k in comments.

    Andres Freund <andres@anarazel.de> — 2021-08-01T21:10:16Z

    Hi,

On 2021-07-31 12:15:34 +0300, Peter Geoghegan wrote:
> On Sat, Jul 31, 2021 at 11:22 AM Andrey Borodin <x4mmm@yandex-team.ru> wrote:
> > FWIW, my 2 cents.
> > I do not see much difference between up2date, up-to-date, up to date, current, recent, actual, last, newest, correct, fresh etc.
> 
> +1.

> To me it seems normal to debate wording/terminology with new code
> comments, but that's about it. I find this zeal to change old code
> comments misguided. It's okay if they're clearly wrong or have typos.
> Anything else is just hypercorrection. And in any case there is a very
> real chance of making the overall situation worse rather than better.
> Probably in some subtle but important way.

Same here. I find them quite distracting, even.

It's one thing for such patches to target blindly obvious typos etc, but
they often also end up including less clear cut changes, which cost a
fair bit of time to review/judge.

Greetings,

Andres Freund

  15. Re: Replace l337sp34k in comments.

    Andrew Dunstan <andrew@dunslane.net> — 2021-08-01T21:27:43Z

    On 8/1/21 5:10 PM, Andres Freund wrote:
> Hi,
>
> On 2021-07-31 12:15:34 +0300, Peter Geoghegan wrote:
>> On Sat, Jul 31, 2021 at 11:22 AM Andrey Borodin <x4mmm@yandex-team.ru> wrote:
>>> FWIW, my 2 cents.
>>> I do not see much difference between up2date, up-to-date, up to date, current, recent, actual, last, newest, correct, fresh etc.
>> +1.
>> To me it seems normal to debate wording/terminology with new code
>> comments, but that's about it. I find this zeal to change old code
>> comments misguided. It's okay if they're clearly wrong or have typos.
>> Anything else is just hypercorrection. And in any case there is a very
>> real chance of making the overall situation worse rather than better.
>> Probably in some subtle but important way.
> Same here. I find them quite distracting, even.
>
> It's one thing for such patches to target blindly obvious typos etc, but
> they often also end up including less clear cut changes, which cost a
> fair bit of time to review/judge.
>

I agree. Errors, ambiguities and typos should be fixed, but purely
stylistic changes should not be made. In any case, I don't think we need
to hold the code comments to the same standard as the docs. I think a
little more informality is acceptable in code comments.


cheers


andrew


--
Andrew Dunstan
EDB: https://www.enterprisedb.com