Re: comments style: Re: [RFC PATCH v4 1/9] printk-rb: add a new printk ringbuffer implementation

Sergey Senozhatsky
2019-08-23T09:49:49Z

On (08/22/19 15:50), Petr Mladek wrote:
[..]
> I could understand that you spend a lot of time on creating the
> labels and that they are somehow useful for you.
>
> But I am not using them and I hope that I will not have to:
>
> + Grepping takes a lot of time, especially over several files.

But without labels one still has to grep. A label at least points
to one exact location.

> + Grepping is actually not enough. It is required to read
> the following comment or code to realize what the label is for.
>
> + Several barriers have multiple dependencies. Grepping one
> label helps to check that one connection makes sense.
> But it is hard to keep all relations in head to confirm
> that they are complete and make sense overall.

Hmm. Labels don't add dependencies per se. Those tricky and hard to
follow dependencies will still be there, even if we'd remove
labels from comments. Labels just attempt to document them and
to show the intent.

The most important label, which should be added, is John's cell
phone number. So people can call/text him when something is not
working ;)

> + There are about 50 labels in the code. "Entry Lifecycle"
> section in dataring.c talks about 8 step. One would
> expect that it would require 8 read and 8 write barriers.
>
> Even coordination of 16 barriers might be complicated to check.
> Where 50 is just scary.
>
> + It seems to be a newly invented format and it is not documented.
> I personally do not understand it completely, for example,
> the meaning of "RELEASE from jA->cD->hA to jB".

I was under impression that this is the lingo used by LMM, but
can't find it in Documentation.

I agree, things can be improved and, may be, standardized.
It feels that tooling is a big part of the problem here.

-ss