Re: [PATCH] checkpatch: add check for NONNETWORKING_BLOCK_COMMENT_STYLE

[Scott Branden]

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