What is the difference between ; and ;; in Clojure code comments?

Clojure Problem Overview

What is the difference between ; and ;; when starting a comment in Clojure? I see that my text editor colours them differently, so I'm assuming there is notionally some difference.

I also see that Marginalia treats them differently:

; Stripped entirely
;; Appears in text section of marginalia
(defn foobar []
   ; Appears in code section of marginalia output
   ;; Again, appears in code section of marginalia output
   6)

Clojure Solutions

Solution 1 - Clojure

There is no difference as far as the interpreter is concerned. Think of ; ;; ;;; and ;;;; as different heading levels.

Here is my personal use convention:

;;;; Top-of-file level comments, such as a description of the whole file/module/namespace

;;; Documentation for major code sections (i.e. groups of functions) within the file.

;; Documentation for single functions that extends beyond the doc string (e.g. an explanation of the algorithm within the function)

; In-line comments possibly on a single line, and possibly tailing a line of code

Solution 2 - Clojure

Check out the official description of the meaning of ; vs ;; in elisp: since the Clojure indenter is basically the same, it will treat them similarly. Basically, use ; if you are writing a long sentence/description "in the margins" that will span multiple lines but should be considered a single entity. Their example is:

(setq base-version-list                 ; there was a base
      (assoc (substring fn 0 start-vn)  ; version to which
             file-version-assoc-list))  ; this looks like
                                        ; a subversion

The indenter will make sure those stay lined up next to each other. If, instead, you want to make several unrelated single-line comments next to each other, use ;;.

(let [x 99 ;; as per ticket #425
      y "test"] ;; remember to test this
  (str x y)) ;; TODO actually write this function

Solution 3 - Clojure

Emacs ; to be used for end-of-line comments and will indent in surprising ways if that is not your intent. ;; does not so I usually use ;;.

Clojure doesn't care - any line is ignored from the ; to EOL.

I believe there is a tradition in CL of using increasing numbers of ; to indicate more important comments/sections.

Solution 4 - Clojure

no meaning for the language. ; is a reader macro for comment perhaps other tools parse them but "within clojure" they are the same.

Solution 5 - Clojure

There is no difference from a Clojure-perspective. I find that ;; stands out a little better than ;, but that's only my opinion.

Marginalia on the other hand treats them differently because there are times when a comment should remain in the code section (e.g. license) and those are flagged with ;. This is an arbitrary decision and may change in the future.

Solution 6 - Clojure

In emacs lisp modes including clojure-mode, ;; is formatted with the convention of being at the beginning of a line, and indented as as any other line, based on the context. ; is expected to be used at the end of a line, so emacs will not do what you want it to if you put a single-semicolon comment at the beginning of a line expecting it to tab to the indentation for the present context.

Example:

(let [foo 1]
  ;; a comment
  foo) ; a comment

Solution 7 - Clojure

I'm not sure (not used Clojure and never heard of this before), but this thread might help.

Content Type	Original Author	Original Content on Stackoverflow
Question	pauldoo	View Question on Stackoverflow
Solution 1 - Clojure	G__	View Answer on Stackoverflow
Solution 2 - Clojure	amalloy	View Answer on Stackoverflow
Solution 3 - Clojure	Alex Miller	View Answer on Stackoverflow
Solution 4 - Clojure	Arthur Ulfeldt	View Answer on Stackoverflow
Solution 5 - Clojure	fogus	View Answer on Stackoverflow
Solution 6 - Clojure	rplevy	View Answer on Stackoverflow
Solution 7 - Clojure	Owen	View Answer on Stackoverflow