Re: [RFC PATCH] line-log: clarify [a,b) notation for ranges

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Aug 7, 2018, 21:47 UTC
Message-ID: <CAPig+cTVEq1AGvtxxonbU4PgqeG0fOy9CSDO7ThjVpfGoJaAJA@mail.gmail.com>
In-Reply-To: <be1dd423-f9de-a436-6127-02cce4ab1977@gmail.com>

On Tue, Aug 7, 2018 at 9:54 AM Andrei Rybak <rybak.a.v@gmail.com> wrote:

> line-log.[ch] use left-closed, right-open interval logic. Change comment
> and debug output to square brackets+parentheses notation to help
> developers avoid off-by-one errors.
> ---

This seems sensible. There might be some reviewers who suggest different notation since "[...)" is not universal (see [1]), but I think this is fine.

You'll want to add your sign-off, of course, when taking this out of RFC.

[1]: https://en.wikipedia.org/wiki/Interval_(mathematics)#Notations_for_intervals

Show 15 quoted lines

> line-log.c also uses ASCII graphics |---| in some comments, like:
>
>         /*
>          * a:         |-------
>          * b: ------|
>          */
>
> But I'm not sure if replacing them with
>
>         /*
>          * a:         [-------
>          * b: ------)
>          */
>
> will be helpful.

Those comments seem to use horizontal ruling to make it clear where one range ends and another begins, so they already do a good job conveying what they represent. Changing them to use "["" and ")" might make them less clear.

Show 5 quoted lines

> Another possibility is to update comment for
> range_set_append_unsafe to read
>
>   /* tack on a _new_ range [a,b) _at the end_ */
>   void range_set_append_unsafe(struct range_set *rs, long a, long b)

It shouldn't hurt (though the existing "_at the end_" is rather superfluous since "append" in the name says the that already).