Should indented comments allow hanging closing parentheses?

[shaunlebron]

The style guide says to “gather trailing parentheses”. Does this imply that the following is incorrect?

(“rich-comment” example from yuhan0’s comment in Standard Clojure Style discussion)

;; Incorrect?
(comment
  (range 5)
  ;; => (0 1 2 3 4)
  (interpose '* (range 5))
  ;; => (0 * 1 * 2 * 3 * 4)
  )

And the following is correct?

;; Correct?
(comment
  (range 5)
  ;; => (0 1 2 3 4)
  (interpose '* (range 5)))
  ;; => (0 * 1 * 2 * 3 * 4)

An auto-formatter might make the above correction to follow the “gather” rule, but then might dedent the comment since it’s no longer inside:

;; More correct?
(comment
  (range 5)
  ;; => (0 1 2 3 4)
  (interpose '* (range 5)))
;; => (0 * 1 * 2 * 3 * 4)

Perhaps to avoid this cascade of corrections, should it be recommended to use a placeholder on the hanging closing paren?

;; Better?
(comment
  (range 5)
  ;; => (0 1 2 3 4)
  (interpose '* (range 5))
  ;; => (0 * 1 * 2 * 3 * 4)
  ,)

Calva uses an :rcf placeholder instead.

[seancorfield]

Calva doesn't need that placeholder, by the way. It has a special rule to allow a trailing ) for a top-level comment form, i.e., that first example is "correct":

(comment
  (range 5)
  ;; => (0 1 2 3 4)
  (interpose '* (range 5))
  ;; => (0 * 1 * 2 * 3 * 4)
  )

[shaunlebron]

Thanks. Is this correct according to Calva or the Style Guide? If it should be the latter, then the Gather Trailing Parens can be updated to clarify which exceptions are allowed. I suppose it can also take a “no comment” stance, but this can also be interpreted as “the Clojure Style Guide doesn’t allow this”.

[seancorfield]

Or you can read my comment as "all style guidelines have exceptions" :)

And they are only guidelines not a Standard™️.

A trailing paren in a comment form makes it easier to work with, easier to comment out lines inside the comment and so on, so I'd argue it's an important exception.

There are plenty of things in the Clojure Style Guide that I don't agree with and don't follow (in some situations).

[shaunlebron]

Some precedents for when to allow hanging closing parentheses in other Lisps:

Riastradh’s Lisp Style Guide

When commenting out fragments of expressions with line comments, it may be necessary to break a line before a sequence of closing brackets. (source)

;; Acceptable
(define (foo bar)
  (list (frob bar)
        (zork bar)
        ;; (zap bar)
        ))

Google Common Lisp Style Guide

An exception to the rule against lonely parentheses is made for an eval-when form around several definitions; in this case, include a comment ; eval-when after the closing parenthesis. (source)

(eval-when ...
(define ...)
(define ...)
(define ...)
) ; eval-when

Racket Style Guide

You are allowed to place all closing parenthesis on a line by itself at the end of long sequences, be those definitions or pieces of data. Doing so is most useful when you expect to add, delete, or swap items in such sequences. (source)

;; Acceptable
(define turn%
  (class object%
    (init-field state)
 
    (super-new)
 
    (define/public (place where tile)
      (send state where tile))
 
    (define/public (is-placable? place)
      (send state legal? place))
    ))

[seancorfield]

PR #263 calls out that exception, so I'm closing this.