How to Comment in Clojure

This article shows:

• How many semicolons to use when writing comments in a Clojure.

• What I want code formatters to do with comments, whether the comments follow the rules or not.

See the Clojure Style Guide for more on the first of these.

An Example Using the Right Numbers of Semicolons    

Here's an example of Clojure code that uses semicolon comments correctly:

;;;; 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))

Note that this example has something not mentioned in the Clojure Style Guide — it shows a good way to indent multi-line single-semicolon comments. The rule is:

• When a trailing comment is followed by one or more single-semicolon comments that are on lines by themselves, line up the semicolons.

What Should a Code Formatter Do with Semicolon Comments?    

First, I'm interested in tools that indent code rather than in more fully-fledged formatters. I want the control of being able to format things myself, but I want standard indentation. So I want to be able to turn off any options that do more than change indentation.

For comments that stick to the style rules, I want code indenters to indent comments as I've shown above. I also want sensible behaviour for comments that break the style rules.

So I suggest the following general rules that can be applied in any case…

For comments that begin with two or more semicolons:

• If the comment is on a line of its own, align it with the code that follows. Note that this means no indentation at the top level.

• If the comment is at the end of a line of code, don't change it.

For single-semicolon comments:

• In general treat these the same way as other comments.

• As shown above, make a special case for a trailing comment that is followed by one or more single-semicolon comments that are on lines by themselves.

An example:

;;;; 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))