Programmer's Guide To Text Blocks
alex.buckley at oracle.com
Mon Aug 5 18:49:14 UTC 2019
On 8/5/2019 5:37 AM, Jim Laskey wrote:
- 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.
More information about the amber-spec-experts