linux-kernel - Re: [PATCH] checkpatch: add check for NONNETWORKING_BLOCK_COMMENT

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <021da2ca-a8d3-d0ad-28c3-6a84464353fd@broadcom.com>
Date:   Wed, 10 Jun 2020 14:33:14 -0700
From:   Scott Branden <scott.branden@...adcom.com>
To:     Joe Perches <joe@...ches.com>, Andy Whitcroft <apw@...onical.com>
Cc:     BCM Kernel Feedback <bcm-kernel-feedback-list@...adcom.com>,
        linux-kernel@...r.kernel.org
Subject: Re: [PATCH] checkpatch: add check for
 NONNETWORKING_BLOCK_COMMENT_STYLE

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 /*