Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
Date:   Fri, 23 Aug 2019 18:49:43 +0900
From:   Sergey Senozhatsky <sergey.senozhatsky.work@gmail.com>
To:     Petr Mladek <pmladek@suse.com>
Cc:     John Ogness <john.ogness@linutronix.de>,
        Sergey Senozhatsky <sergey.senozhatsky.work@gmail.com>,
        Andrea Parri <andrea.parri@amarulasolutions.com>,
        Sergey Senozhatsky <sergey.senozhatsky@gmail.com>,
        Steven Rostedt <rostedt@goodmis.org>,
        Brendan Higgins <brendanhiggins@google.com>,
        Peter Zijlstra <peterz@infradead.org>,
        Thomas Gleixner <tglx@linutronix.de>,
        Linus Torvalds <torvalds@linux-foundation.org>,
        Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
        linux-kernel@vger.kernel.org
Subject: Re: comments style: Re: [RFC PATCH v4 1/9] printk-rb: add a new
 printk ringbuffer implementation
Message-ID: <20190823094943.GA15662@jagdpanzerIV>
References: <20190807222634.1723-1-john.ogness@linutronix.de>
 <20190807222634.1723-2-john.ogness@linutronix.de>
 <20190820085554.deuejmxn4kbqnq7n@pathway.suse.cz>
 <20190820092731.GA14137@jagdpanzerIV>
 <87a7c3f4uj.fsf@linutronix.de>
 <20190822135052.dp4dvav6fy2ajzkx@pathway.suse.cz>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20190822135052.dp4dvav6fy2ajzkx@pathway.suse.cz>
User-Agent: Mutt/1.12.1 (2019-06-15)
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

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