Programmer's Guide To Text Blocks

[Alex Buckley]

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.

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

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

- "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).

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

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

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

Alex