Open uvtc opened 11 years ago
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). :)
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.
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:
Seems to me markdown is preferable to that. And also, many folks generally use some markdown in comments already (italics and code
, for example).
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).