How do we deal with comments?

[danielcompton]

trafficstars

How should we deal with comments? Is there a difference between ; and ;;?

Reading discussions of other people building source code formatters, comments came up many times as a very tricky thing to deal with properly.

[simon-katz]

Some thoughts from an old-time Lisper. (More detail at http://blogish.nomistech.com/how-to-comment-in-clojure/.)

An example of what I think is correct use of semicolons:

;;;; A top-level comment with four semicolons.
;;; A top-level comment with three semicolons.
;;;    I am allowed to indent like this after the semicolons.

(defn foo []
  ;; An inline comment.
  ;;    I am allowed to indent like this after the semicolons.
  (let [a {;; An inline comment on a code line
           ;; - maybe a contradiction in terms.
           :a 1
           ;; An inline comment.
           }]
    (f a) ; A trailing comment. This might be long enough
          ; to need more than one line.
          ;     Perhaps many lines.
    ;; Another inline comment.
    a))

An example of what I think an indenter should do when the number of semicolons is wrong:

;;;; Remove any indentation.
;;; Remove any indentation.
;; Remove any indentation.
; Remove any indentation.

(defn foo []
  ;;;; Align with the following code.
  ;;; Align with the following code.
  ;; Align with the following code.
  ; Align with the following code.
  (let [a {;;;; Align with the following code.
           ;;; Align with the following code.
           ;; Align with the following code.
           ; Align with the following code.
           :a 1 ; Leave as is.
                ; Align with the above.
                ; Align with the above.
           ;;;; Align with the following code.
           ;;; Align with the following code.
           ;; Align with the following code.
           ; Align with the following code.
           }]
    (f a) ; Leave as is.
          ; Align with the above.
          ; Align with the above.
    ;;;; Align with the following code.
    ;;; Align with the following code.
    ;; Align with the following code.
    ; Align with the following code.
    a))

[danielcompton]

Thanks @simon-katz that's really helpful. What would be idiomatic to do with code where there is lots of whitespace between the end of the code on the line and the comment? Is that collapsed or left as-is?

(def foo nil)               ;; Comment

;; Does the above reformat to this?

(def foo nil) ;; Comment

[simon-katz]

@danielcompton

In your example I would vote for leaving the whitespace before the first semicolon unchanged. Here's an example of why:

(def foo nil)        ; Comment
(def foo-longer nil) ; Aligned with the above comment

This is part of a more general view of mine that I only want an indenter, not a formatter. By that I mean I only want the leading spaces on a line to be adjusted. Then I have control of how I use whitespace everywhere else, so, for example:

• I can choose to align let forms or not on a case by case basis. (And, for example, I have an align-cljlet command in my Emacs to make that easy.)
• If I want some weird spacing after an open bracket to highlight commonality with a previous or following line, I can do that.

I hope to find some time in the next few days to write up these thoughts in a bit more detail and with examples — it seems like it's the hot topic at the moment so now would be a good time.

EDIT: Actually, I'd be happy for more formatting (beyond indentation) as options. But by default I'd want just an indenter. I mentioned that before here in the original discussion, so I really need to pull my thoughts together in one place.