heading, top-level, and trailing comments

[uvtc]

Re. "The only comments in which omission of a space between the semicolon and the text is acceptable are margin comments."

Leaving out the space there looks bad, IMO. I don't think that should be in the style guide.

Also, where does the tradition of triple and quadruple semicolons come from? Is that from Elisp? The only Clojure project I know of that reads comments --- and does something with them --- is Marginalia. AFAIK, it treats full-line comments as markdown input, and uses the double-semicolon throughout. For example, see https://github.com/fogus/marginalia/blob/master/src/marginalia/core.clj .

If anything, I'd recommend that comments be written in such a way as to be correctly renderable by Marginalia (I haven't looked into how it handles triple and quad semicolons).

[uvtc]

Incidentally, and related to this topic: where you, for example, have

;;; object creation
;; good
(java.util.ArrayList. 100)

;; bad
(new java.util.ArrayList 100)

;;; static method invocation
;; good
(Math/pow 2 10)

;; bad
(. Math pow 2 10)

I'd be tempted to make that:

;; ## object creation
;; good
(java.util.ArrayList. 100)

;; bad
(new java.util.ArrayList 100)

;; ## static method invocation
;; good
(Math/pow 2 10)

;; bad
(. Math pow 2 10)

such that "object creation" and "static method invocation" now look more like (H2) headings (both to the reader, and to the marginalia parser). :)

[bbatsov]

The tradition dates back to Scheme AFAIK and is considered the facto standard in every Lisp. The margin exception rule is pretty common and I basically copied it from the Scheme style guide, but I dislike it as well and I'll probably remove it soon. I do like the triple and quadruple comments - they carry semantic information and that's not a bad thing.

[uvtc]

The tradition dates back to Scheme AFAIK and is considered the facto standard in every Lisp.

My guess is, that tradition may be changing with Clojure (just my 2 cents). I very much like the idea having comments in markdown. This way, if I'm away from some code for weeks/months, and want to quickly come to terms with it, I can have Marginalia process it and read through nicely-rendered (as html) comments side-by-side with the code. (Likewise, if I'm learning my way around someone else's code.)

If there were another popular tool like Marginalia which maybe rendered ";;; foo" ---> <h2>foo</h2>, ";;;; foo" --> <h1>foo</h1>, I could imagine the repeated semicolon syntax maybe being useful, but it's still problematic:

• for one thing, I have to count semicolons
• for another, there's no h3 (unless you make ;;; --> h3, ;;;; --> h2, ;;;;; --> h1).

Seems to me markdown is preferable to that. And also, many folks generally use some markdown in comments already (italics and code, for example).