Skip to contentSkip to conversation

checkpatch: add check for NONNETWORKING_BLOCK_COMMENT_STYLE

PATCH Superseded Scott Branden 2 participants 6 messages Jun 10, 2020 Checkpatch

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 checkpatch: add check for NONNETWORKING_BLOCK_COMMENT_STYLE

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.

---
 scripts/checkpatch.pl | 10 ++++++++++
 1 file changed, 10 insertions(+)
scripts/checkpatch.pl +10 -0
index 524df88f9364..899e380782c0 100755
@@ -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 /*
Signature · 1 line
2.17.1
maintainer
#1 lore raw
Quoted 4 lines · Scott Branden

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

(with a few false positives)

Does anyone really care if non-network code uses
this style?

	/* multiline
	 * comment
	 */

scripts/checkpatch.pl

Quoted 1 line
scripts/checkpatch.pl +0 -0

[]

Quoted 17 lines
scripts/checkpatch.pl +10 -0
@@ -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 /*
#2 lore raw

Hi Joe,

Quoted 5 lines · Joe Perches
Quoted 4 lines · Scott Branden

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.

Quoted 7 lines

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

Quoted 5 lines

(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.

Quoted 24 lines
	/* multiline
	 * comment
	 */

scripts/checkpatch.pl

Quoted 1 line
scripts/checkpatch.pl +0 -0

[]

Quoted 17 lines
scripts/checkpatch.pl +10 -0
@@ -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 /*
maintainer
#3 lore raw
Quoted 11 lines · Scott Branden

Hi Joe,

Quoted 8 lines · Joe Perches
Quoted 4 lines · Scott Branden

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.

Quoted 6 lines
Quoted 4 lines
$ 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.

Not in that quantity of uses it doesn't.

I specifically did _not_ add this very same test
when I added the other comment tests.

Quoted 2 lines

But, by adding to checkpatch the coding style clearly outlined in coding-style.rst can be followed:

Well, because there are _so_ many false positives
that don't need change, I'm not adding this.

As is, I'm nacking it.

If you need it for your use, you should keep it in your own tree.

Quoted 6 lines
Quoted 6 lines

scripts/checkpatch.pl

Quoted 1 line
scripts/checkpatch.pl +0 -0

[]

Quoted 4 lines
scripts/checkpatch.pl +0 -0
@@ -3408,6 +3408,16 @@ sub process {
  			     "networking block comments don't use an empty /* line, use /* Comment...\n" . $hereprev);
  		}
 
Quoted 8 lines
Quoted 8 lines

scripts/checkpatch.pl sub process { · line 3418

Quoted 8 lines
scripts/checkpatch.pl +8 -0
+# 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);

_Maybe_ this test _might_ be useful if it did a file/patch test and used CHK on file, but even then I'm very dubious.

			my $msg_level = \&WARN;
			$msg_level = \&CHK if ($file);
			&{msg_level}(etc...)
#4 lore raw

Hi Joe,

Quoted 25 lines · Joe Perches
Quoted 11 lines · Scott Branden

Hi Joe,

Quoted 8 lines · Joe Perches
Quoted 4 lines · Scott Branden

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.

Quoted 6 lines
Quoted 4 lines
$ 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.

Not in that quantity of uses it doesn't.

I specifically did _not_ add this very same test
when I added the other comment tests.

Quoted 2 lines

But, by adding to checkpatch the coding style clearly outlined in coding-style.rst can be followed:

Quoted 7 lines

Well, because there are _so_ many false positives
that don't need change, I'm not adding this.

As is, I'm nacking it.

If you need it for your use, you should keep it in your own tree.

I think this has value for others.

Quoted 18 lines
Quoted 7 lines
Quoted 7 lines

scripts/checkpatch.pl

Quoted 2 lines
scripts/checkpatch.pl +0 -0

[]

Quoted 4 lines
scripts/checkpatch.pl +0 -0
@@ -3408,6 +3408,16 @@ sub process {
   			     "networking block comments don't use an empty /* line, use /* Comment...\n" . $hereprev);
   		}
 
Quoted 8 lines
Quoted 8 lines

scripts/checkpatch.pl sub process { · line 3418

Quoted 8 lines
scripts/checkpatch.pl +8 -0
+# 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);

_Maybe_ this test _might_ be useful if it did a file/patch test and used CHK on file, but even then I'm very dubious.

Quoted 3 lines
			my $msg_level = \&WARN;
			$msg_level = \&CHK if ($file);
			&{msg_level}(etc...)

I can make such change.
As is, checkpatch basically follows the coding style documented for networking and has no check for outside.

I do not know the history of the 2 block coding styles but here's a radical thought:
Change the coding-style document to pick a single coding style for ALL block comment styles and use that going forward in checkpatch instead?

Quoted 2 lines
maintainer
#5 lore raw
Quoted 1 line · Scott Branden

Hi Joe,

Hi Scott.

Quoted 5 lines

I do not know the history of the 2 block coding styles but here's a radical thought:
Change the coding-style document to pick a single coding style for ALL block comment styles and
use that going forward in checkpatch instead?

Opinions vary.
Good luck with that.
Seriously.