76

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)
pauldoo
  • 18,087
  • 20
  • 94
  • 116

7 Answers7

88

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
ntalbs
  • 28,700
  • 8
  • 66
  • 83
G__
  • 7,003
  • 5
  • 36
  • 54
  • I guess I have to mark this as correct given the number of upvotes. An external reference would be nice, but I guess it's an unwritten culture thing. :) – pauldoo Feb 23 '11 at 19:39
  • 4
    For reference, Peter Norvig, the author of *Good Lisp Programming Style*, among a lot of other things, refers to this convention as a "near standard". http://stackoverflow.com/a/4531930/603891 – orftz Apr 19 '12 at 01:06
  • 1
    Then why no mention of single `;` in the doc? https://clojuredocs.org/clojure.core/comment – matanster Mar 04 '17 at 09:35
  • @matanster That link is about (comment) not ;. But FTR the second paragraph in the largest example does indeed discuss a single ;. For canonical doc on the ; reader macro check https://clojure.org/reference/reader#macrochars – G__ Jun 17 '18 at 16:56
34

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
amalloy
  • 89,153
  • 8
  • 140
  • 205
16

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.

Alex Miller
  • 69,183
  • 25
  • 122
  • 167
7

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

Arthur Ulfeldt
  • 90,827
  • 27
  • 201
  • 284
6

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.

fogus
  • 6,126
  • 5
  • 36
  • 42
  • 3
    fogus, notice alex miller's comment about emacs. It indents single ; comments but not ;; or ;;; If you don't use emacs yourself, you should be aware of what its auto-indentation scheme does, because a lot of your target users will. – John Lawrence Aspden Feb 23 '11 at 17:04
6

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
rplevy
  • 5,393
  • 3
  • 32
  • 31
1

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

Community
  • 1
  • 1
Owen
  • 1,541
  • 1
  • 14
  • 12
  • Those styles look completely incompatible with variable width fonts. I hope the Clojure community hasn't adopted the column alignment thing for comments. – pauldoo Feb 22 '11 at 22:03