Programmer's Guide To Text Blocks

[Jim Laskey]

Thank you.

> On Aug 5, 2019, at 3:49 PM, Alex Buckley <Alex.Buckley at oracle.com> wrote:
> 
> On 8/5/2019 5:37 AM, Jim Laskey wrote:
>> http://cr.openjdk.java.net/~jlaskey/Strings/TextBlocksGuide_v8.html
> 
> - Please number the guidelines like in the var style guidelines.
> 

Done .

> - "Guideline: If a string literal fits on a single line" -- A string literal CAN ONLY fit on a single line; you mean "If a string fits ..."

Done.

> 
> - "Guideline: Most text blocks should be indented to align with neighbouring Java code."  should come after "Guideline: Avoid aligning the opening and closing delimiters"

Done.

> 
> - "Guideline: Avoid in-line text blocks within complex expressions" -- now your readers are wondering why a normal `for` loop is "complex". You're going for something about: be cautious using text blocks in nested expressions. A `for` loop which pushes the text block down one level, into the `for` header, is an example; another example would be passing a text block in a method call (which is probably OK); another example would be passing a text block in a truly madly deeply nested expression (which isn't OK; show one).

// ORIGINAL
String poem = new String(Files.readAllBytes(Paths.get("jabberwocky.txt")));
String middleVerses = Pattern.compile("\\n\\n")
                             .splitAsStream(poem)
                             .match(verse -> !"""
                                   ’Twas brillig, and the slithy toves
                                   Did gyre and gimble in the wabe;
                                   All mimsy were the borogoves,
                                   And the mome raths outgrabe.
                                   """.equals(verse))
                             .collect(Collectors.joining("\n\n"));

// BETTER
String firstLastVerse = """
    ’Twas brillig, and the slithy toves
    Did gyre and gimble in the wabe;
    All mimsy were the borogoves,
    And the mome raths outgrabe.
    """;
String poem = new String(Files.readAllBytes(Paths.get("jabberwocky.txt")));
String middleVerses = Pattern.compile("\\n\\n")
                             .splitAsStream(poem)
                             .match(verse -> !firstLastVerse.equals(verse))
                             .collect(Collectors.joining("\n\n"));


> 
> - IMO a variable declaration with a text block on the RHS cries out for a `var` on the LHS. The """ is as clear a marker as you'll ever get about the inferred type of the variable. Is there a reason to not use `var` almost everywhere here, and to explicitly recommend that?

I would agree except this is not a discussion about the cleverness of the "var" feature, it is about the String-y-ness of the text block feature.  Repeated emphasis highlighting String will surely drive that aspect home.

> 
> - I think there should be a guideline that says it's OK to have \n sequences in a text block -- there may be times when that's more readable overall than physically introducing a newline.


(Alex provided an example.)

> 
> - "Guideline: It is sometimes reasonable to fully left justify a wide string" -- I think it's not merely reasonable, I think it's recommended.

Done.

> 
> - "... when the closing delimiter is likely to scroll out of view." -- when does this happen? There's context here which is not stated in the guidelines, especially when an earlier guideline said to put the closing delimiter on its own line.

G10. Similarly, it is also reasonable to fully left justify a text block when a high line count causes the closing delimiter is likely to vertically scroll out of view. This allows the reader to track indentation with the left margin when the closing delimiter is out of view.

	example

> 
> Alex

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/amber-spec-experts/attachments/20190806/cc306914/attachment.html>