Google-style: New Check TextBlockGoogleStyleFormattingCheck (original) (raw)

From #17159

TextBlockGoogleStyleFormattingCheck should validate if the Opening and closing quotes of java text-blocks are on new lines. Google-style demands opening and closing (""") should always be on new lines.

https://google.github.io/styleguide/javaguide.html#s4.8.9-text-blocks

The opening """ of a text block is always on a new line. That line may either follow the same indentation rules as other constructs, or it may have no indentation at all (so it starts at the left margin). The closing """ is on a new line with the same indentation as the opening """, and may be followed on the same line by further code

Example Config:

$ cat config.xml

TextBlocks.java Example:

$ cat TextBlocks.java public class TextBlocks {

public static String textFun(String[] args) {

// violation below, 'Opening quotes (""") of text-block must be on the new line.'
final String simpleScript = """ 
    s
    """;  // OK

final String simpleScript1 = 
    """  // OK
    this is simple test;
    """;  // OK

final String simpleScript2 = 
    """  // OK
    this is sample text """; 
    // violation above, 'Opening quotes (""") of text-block must be on the new line.'

String s = 
        """
          Hello there
        """ + getName();  // OK 

// violation below, 'Opening quotes (""") of text-block must be on the new line.'  
return """
    this is sample text 
    """;  // OK

} }

Expected Output:

$ java -jar testing/checkstyle-10.25.0-all.jar -c config.xml TextBlocks.java 
Starting audit...
[WARN] TextBlocks.java:5: Opening quotes (""") of text-block must be on the new line. [TextBlockGoogleStyleFormattingCheck]
[WARN] TextBlocks.java:17: Closing quotes (""") of text-block must be on the new line. [TextBlockGoogleStyleFormattingCheck]
[WARN] TextBlocks.java:28: Opening quotes (""") of text-block must be on the new line. [TextBlockGoogleStyleFormattingCheck]
Audit done.

Some other examples showing how the check should work

CASE 1: Placement of opening quotes:

public static String textFun() { 

// violation below, 'Opening quotes (""") of text-block must be on the new line.'
final String simpleScript = """ 
    s
    """;

// OK
final String simpleScript1 = 
    """  
    this is simple test;
    """;

// violation below, 'Opening quotes (""") of text-block must be on the new line.'
getData(""" 
    Hello,
    This is a multi-line message.
""");

// violation below, 'Opening quotes (""") of text-block must be on the new line.'
return """
    this is sample text 
    """;

}

CASE 2: Placement of Closing quotes:

public String textFun2() {

final String simpleScript2 = 
  """
    this is sample text """;  
    // violation above, 'Closing quotes (""") of text-block must be on the new line.'

  getData(
      """
      Hello,
      This is a multi-line message."""
      // violation above, 'Closing quotes (""") of text-block must be on the new line.'
  );

  return 
      """
        THE MULTI-LINE MESSAGE """; // violation, 'Closing quotes (""") of text-block must be on the new line.'

}

CASE 3: Closing quotes followed by some expression

public String textFun3() {

String s = 
    """
      Hello there
    """ + getName();  // OK

getData(
  """
    hello there1
  """, 0);  // OK

return s + 
    """
    very good
    """.charAt(0) + getName();  // OK

}

CASE 4 : Indentation
Checking indentation of text-block is the second function of this Check.

That line may either follow the same indentation rules as other constructs, or it may have no indentation at all (so it starts at the left margin).

Opening quotes can have indentation of 0 or indentation value of parent + lineWrappingIndentation.
Value of lineWrappingIndentation is 4 in style-guide.
For closing quotes, we just need to make sure they are vertically aligned with opening quotes.

public void textFun4() {

// OK 
String e1 =
    """
  content of the block. e1
    """;

// According to rule following is OK, but code does not look clean. 
String e2 =

"""
content of the block e2 """;

String e3 = 
    """
    content of the block of e3
        """;
// violation above, 'Text-block quotes are not vertically aligned. '

// OK
getData(
  """
    Indentation of Text-block 
  """,
  5
);

}

Behaviour of Indentation Check on Java textblocks: Indentation Check only gives violation if actual indentation of opening or closing quotes is less can expected indentation

CASE 4a: indenation is more than expected

/** somejavadoc. */ public class TextBlockIndentation {

/** somejavadoc. */ public void textIndentation1() { String e1 = """ content of the block. e1 """;

String e2 = 
    """
    content of the block of e3 
        """; // EXPECTED VIOLATION ON CLOSING """

// EXPECTED VIOLATION ON OPENING """
String e3 =
      """ 
  content of the block. e1
    """;

// EXPECTED VIOLATION ON OPENING AND CLOSING """s
getData(
        """
    Indentation of Text-block 
        """,
    5
);

}

$ java -jar checkstyle-10.25.0-all.jar -c google_checks.xml TextBlockIndentation.java 
Starting audit...
Audit done.

Google Formatter:

$ java -jar google-java-format-1.27.0-all-deps.jar TextBlockIndentation.java > FormattedCode.java && diff -Naru TextBlockIndentation.java FormattedCode.java --- TextBlockIndentation.java 2025-06-27 18:35:13.709744600 +0530 +++ FormattedCode.java 2025-06-27 18:54:42.372702500 +0530 @@ -6,27 +6,26 @@ // OK String e1 = """ - content of the block. e1 + content of the block. e1 """; - String e2 = + String e2 = """ - content of the block of e3 - """; // EXPECTED VIOLATION

CASE 4b: Indentation is more than expected

In the first example, indentation of both the quotes is 0 which is valid according to the rule, but Indentation Check, as expected, gives violation on it.

/** somejavadoc. */ public void textFuncIndenation2() { String e2 = """ content of the block e2 """;

getData(  // OK
""" 
    Indentation of Text-block 
""",
    5
);

}

Starting audit...
[WARN] /mnt/5D92528E6B945467/test/testing/TextBlockIndentation.java:4:1: '"""' has incorrect indentation level 0, expected level should be 8. [Indentation]
[WARN] /mnt/5D92528E6B945467/test/testing/TextBlockIndentation.java:6:1: '"""' has incorrect indentation level 0, expected level should be 8. [Indentation]
[WARN] /mnt/5D92528E6B945467/test/testing/TextBlockIndentation.java:9:5: 'method call' child has incorrect indentation level 4, expected level should be 6. [Indentation]
[WARN] /mnt/5D92528E6B945467/test/testing/TextBlockIndentation.java:11:5: 'method call' child has incorrect indentation level 4, expected level should be 6. [Indentation]
Audit done.

Google Formatter:

$ java -jar google-java-format-1.27.0-all-deps.jar TextBlockIndentation.java > FormattedCode.java && diff -Naru TextBlockIndentation.java FormattedCode.java --- TextBlockIndentation.java 2025-06-27 18:35:13.709744600 +0530 +++ FormattedCode.java 2025-06-27 18:59:26.774067900 +0530 /** somejavadoc. */ @@ -36,16 +35,13 @@ content of the block e2 """; 

 getData(

FYI, Indentation Check ignores the content of text-block, and that's fine because style guide does not mention it either.