Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
Subject: Re: [PATCH] checkpatch: add check for
 NONNETWORKING_BLOCK_COMMENT_STYLE
To:     Joe Perches <joe@perches.com>, Andy Whitcroft <apw@canonical.com>
Cc:     BCM Kernel Feedback <bcm-kernel-feedback-list@broadcom.com>,
        linux-kernel@vger.kernel.org
References: <20200610202640.9020-1-scott.branden@broadcom.com>
 <673c2ebaf7a1ca93f3b1192a77ff62167badd896.camel@perches.com>
From:   Scott Branden <scott.branden@broadcom.com>
Message-ID: <021da2ca-a8d3-d0ad-28c3-6a84464353fd@broadcom.com>
Date:   Wed, 10 Jun 2020 14:33:14 -0700
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101
 Thunderbird/68.8.0
MIME-Version: 1.0
In-Reply-To: <673c2ebaf7a1ca93f3b1192a77ff62167badd896.camel@perches.com>
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 8bit
Content-Language: en-US
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

Hi Joe,

On 2020-06-10 2:16 p.m., Joe Perches wrote:
> On Wed, 2020-06-10 at 13:26 -0700, Scott Branden wrote:
>> NETWORKING_BLOCK_COMMENT_STYLE is supported by checkpatch but there
>> doesn't seem to be any check for the standard block comment style.
>> Add support for NONNETWORKING_BLOCK_COMMENT_STYLE to check for empty /*
>> on first line of non-networking block comments.
> I think there are _way_ too many instances of this form
> in non-networking code to enable this.
>
> $ git grep -P '^\s*/\*\s*\S.*[^\*][^\\]\s*$' -- '*.[ch]' | \
>    grep -v -P '^(drivers/net/|net/)' | \
>    wc -l
> 51407
That is true about many things that checkpatch now checks for that 
didn't previously.
But, by adding to checkpatch the coding style clearly outlined in 
coding-style.rst can be followed:

The preferred style for long (multi-line) comments is:

.. code-block:: c

     /*
      * This is the preferred style for multi-line
      * comments in the Linux kernel source code.
      * Please use it consistently.
      *
      * Description:  A column of asterisks on the left side,
      * with beginning and ending almost-blank lines.
      */

For files in net/ and drivers/net/ the preferred style for long (multi-line)
comments is a little different.

.. code-block:: c

     /* The preferred comment style for files in net/ and drivers/net
      * looks like this.
      *
      * It is nearly the same as the generally preferred comment style,
      * but there is no initial almost-blank line.
      */
>
> (with a few false positives)
>
> Does anyone really care if non-network code uses
> this style?
Yes we do.
Consistent coding style is great and keeps your brain able to focus on 
what matters when it is consistent.
>
> 	/* multiline
> 	 * comment
> 	 */
>
>> diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
> []
>> @@ -3408,6 +3408,16 @@ sub process {
>>   			     "networking block comments don't use an empty /* line, use /* Comment...\n" . $hereprev);
>>   		}
>>   
>> +# Non-Networking with an empty initial /*
>> +		if ($realfile !~ m@^(drivers/net/|net/)@ &&
>> +		    $prevrawline =~ /^\+[ \t]*\/\*[ \t]/ &&
>> +		    $prevrawline !~ /\*\/[ \t]*$/ &&		#no trailing */
>> +		    $rawline =~ /^\+[ \t]*\*/ &&
>> +		    $realline > 2) {
>> +			WARN("NONNETWORKING_BLOCK_COMMENT_STYLE",
>> +			     "non-networking block comments use an empty /* on first line\n" . $hereprev);
>> +		}
>> +
>>   # Block comments use * on subsequent lines
>>   		if ($prevline =~ /$;[ \t]*$/ &&			#ends in comment
>>   		    $prevrawline =~ /^\+.*?\/\*/ &&		#starting /*