Search code examples
clojurecommentsmarginalia

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


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)

Solution

  • 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