3 ms·
I agree that this is a pretty good style guide, in the sense that it captures a large portion of what Clojure programmers consider to be good style. A few word
by dj-wonk 12y ago
I agree that this is a pretty good style guide, in the sense that it captures a large portion of what Clojure programmers consider to be good style.
A few words about semicolons for comments. Lots of Clojure code uses ; and ;; and ;;; to indicate levels of comment nesting. I get that multiple semicolons are intended to indicate hierarchy / sections / nesting. Some editors use it for auto-indentation. (However, I don't think editors really need multiple semicolons to do a good job of indentation; mine does fine without.)
Personally, I find one semicolon to be enough to indicate a comment at any level. Context tells the rest. So I am not on-board with multiple semicolons. One, it looks ugly to me. Two, using more than one seems unnecessary -- and unnecessary things are good to avoid unless they add value.
Who else agrees? Is there something I'm missing?
- th0ma5 12y agoSometimes I use an editor with a highlight and comment feature, and if I comment out a block of code, some of those intertwined comments will have the double semicolon. Another neurosis I have is using multiple for stuff that I've yet to delete but want to make sure I don't accidentally uncomment but that is dumb and what version control solves. Outside of these unconvincing uses I'm not familiar with this nested comment idea but I couldn't criticize it given the funny things I do.
- TheMiller 12y agoI believe that this convention is borrowed from Common Lisp. I always thought of it more as a way to highlight importance. Three semicolons for block comments outside of top-level constructs, which usually explain the purpose or usage of the following expression (usually a function definition). Two for comments inline with function body code. And one for trailing comments on a line, where space is limited and the comment is least important to understand code structure. The conventions are even mentioned in the Common Lisp specifications: http://www.lispworks.com/documentation/HyperSpec/Body/02_ddb.htm http://www.lispworks.com/documentation/HyperSpec/Body/02_ddb...
- lispm 12y agoThe use of one or more semicolons is older than Common Lisp. Maclisp had it in the 1970s, but earlier with different semantics - it had semantics for formatting code. Then it was changed a bit with the use of Emacs.
- thom 12y agoI've used Marginalia[1] in the past, which more or less embeds markdown in clojure comments as a sort of literate programming lite. It has the payoff that it can generate rather nice docs[2] but without something like that, I'm not sure there's much benefit to the hierarchy. [1] https://github.com/gdeer81/marginalia https://github.com/gdeer81/marginalia [2] http://gdeer81.github.io/marginalia/ http://gdeer81.github.io/marginalia/