making code readable
Mark Volkmann
a lot of time studying the code in this "snake" example and have some
observations I'd like to share.
First off, obviously I care about the future of Clojure or I wouldn't
have spent the last six weeks or so trying to learn it.
I imagine that almost everyone on this mailing list would like to have
the opportunity to spend more time on the job coding in Clojure than
they get to currently. One way to make that more likely is to make it
easier for others to learn Clojure. You may not be allowed to use it
for production code if you're the only one in your company that can
understand it.
Many examples of Clojure code work counter to this goal. This snake
code is just one of them. I don't mean to pick on the authors. This
code is very similar to other Clojure code I encounter daily.
Here are some things I think we could all do in our Clojure code to
make it easier for others to understand.
1) There are no prizes for using one letter variable names. Pick more
meaningful names.
For example, (defn collision? [{[b] :body} a] ...).
What is a? It's a vector containing the x/y coordinates of the apple
the snake is trying to eat. Why not name it "apple" or
"apple-location"?
What is b? It's a vector that represents the x/y coordinates of the
head of the snake.
Why not name it "head" or "snake-head"?
2) There are no prizes for writing code with zero comments. One of the
strengths of Clojure is that you can accomplish a large amount in a
small amount of code. That doesn't mean that readers of your code will
know what is going on though.
For example, what does this do?
(every? #(<= (- (a %) 10) (b %) (+ 10 (a %))) [0 1])
Well, 0 and 1 are indexes of the x and y coordinates represented by
two element vectors that represent the location of the apple and the
head of the snake. This tests whether every coordinate (the x and y)
of the apple are "close" to the corresponding coordinate of the snake
head. This certainly needs to be explained in a comment.
3) There are no prizes for cramming loads of functionality into a
single line. Spread it out to make it easier to read.
For example, which of these is easier to understand?
; original
(assoc snake :body (cons (vec (map #(+ (dir %) ((first body) %)) [0 1]))
(if grow body (butlast body)))))
What is being cons'ed to what here?
; modified
(assoc snake :body
(cons
(vec (map #(+ (dir %) ((first body) %)) [0 1]))
(if grow body (butlast body))
)
)
I know my placement of the closing parens on separate lines is
non-standard in the Lisp world, but I find it helps me see better
where constructs end. Without doing that it feels like Python where
indentation is significant. I could concede the paren placement
though.
Below is the original code. Compare it to my version at
http://pastie.org/348031 where variables are renamed, comments are
added, and indentation is changed in a way that I feel makes it more
readable.
(import '(java.awt Color) '(javax.swing JPanel JFrame Timer)
'(java.awt.event KeyEvent ActionListener KeyListener))
(defn gen-apple [_] [(rand-int 750) (rand-int 550)])
(defn move [{:keys [body dir] :as snake} & grow]
(assoc snake :body (cons (vec (map #(+ (dir %) ((first body) %)) [0 1]))
(if grow body (butlast body)))))
(defn turn [snake newdir] (if newdir (assoc snake :dir newdir) snake))
(defn collision? [{[b] :body} a]
(every? #(<= (- (a %) 10) (b %) (+ 10 (a %))) [0 1]))
(defn paint [g p c] (.setColor g c) (.fillRect g (p 0) (p 1) 10 10))
(def dirs {KeyEvent/VK_LEFT [-10 0] KeyEvent/VK_RIGHT [10 0]
KeyEvent/VK_UP [0 -10] KeyEvent/VK_DOWN [0 10]})
(def apple (atom (gen-apple nil)))
(def snake (atom {:body (list [10 10]) :dir [10 0]}))
(def colors {:apple (Color. 210 50 90) :snake (Color. 15 160 70)})
(def panel (proxy [JPanel ActionListener KeyListener] []
(paintComponent [g] (proxy-super paintComponent g)
(paint g @apple (colors :apple))
(doseq [p (:body @snake)]
(paint g p (colors :snake))))
(actionPerformed [e] (if (collision? @snake @apple)
(do (swap! apple gen-apple)
(swap! snake move :grow))
(swap! snake move))
(.repaint this))
(keyPressed [e] (swap! snake turn (dirs (.getKeyCode e))))
(keyReleased [e])
(keyTyped [e])))
(doto panel (.setFocusable true)(.addKeyListener panel))
(doto (JFrame. "Snake")(.add panel)(.setSize 800 600)(.setVisible true))
(.start (Timer. 75 panel))
Another example of a fairly short piece of code that is begging for
comments is the example at http://clojure.org/concurrent_programming.
Imagine someone who has only been learning Clojure for a couple of
days and is curious about how Clojure handles concurrency trying to
follow what is happening in that code.
So my main point is that if we all make an effort to make our code
easier to read, it will be easier to convince other developers to
consider learning Clojure which will be good for all of us.
--
R. Mark Volkmann
Object Computing, Inc.
Rich Hickey
> days and is curious about how Clojure handles concurrency trying to
> follow what is happening in that code.
>
> So my main point is that if we all make an effort to make our code
> easier to read, it will be easier to convince other developers to
> consider learning Clojure which will be good for all of us.
>
most of your example.
Making something 4x longer does not make it easier to read.
Redundant comments are useless.
Trailing parens are known bad - don't use them.
Though when first learning you might wish every piece of code had a
built-in language tutorial, I'd be dismayed if, e.g., every use of
proxy contained this redundant description of how it works:
; Create a proxy object that extends JPanel and
; implements both ActionListener and KeyListener.
(proxy [JPanel ActionListener KeyListener]
[] ; arguments to the superclass constructor (none here)
; What follows are implementations of the interface methods.
etc. Most of your comments don't say anything that the code doesn't.
Those that do may be worthwhile, those that don't should not be in non-
tutorial code.
The original code was not intended as a tutorial, nor is most code,
nor should it be.
'X in Y lines of code' examples are inherently trying to be concise,
and probably not the best things to learn from initially.
Rich
Mark Volkmann
I agree ... if they are really redundant. For example, I don't feel
that explaining the use of [0, 1] to represent indexes for x and y
values is redundant.
> Trailing parens are known bad - don't use them.
I'm not disagreeing, but I'd like to hear the explanation for why they
are bad. The ones that end defn's seem the same as Java's trailing
braces to me.
> Though when first learning you might wish every piece of code had a
> built-in language tutorial, I'd be dismayed if, e.g., every use of
> proxy contained this redundant description of how it works:
>
> ; Create a proxy object that extends JPanel and
> ; implements both ActionListener and KeyListener.
> (proxy [JPanel ActionListener KeyListener]
> [] ; arguments to the superclass constructor (none here)
>
> ; What follows are implementations of the interface methods.
Right. I agree with you there and I did put those in my code because
that was my first exposure to Clojure proxies.
> etc. Most of your comments don't say anything that the code doesn't.
> Those that do may be worthwhile, those that don't should not be in non-
> tutorial code.
>
> The original code was not intended as a tutorial, nor is most code,
> nor should it be.
>
> 'X in Y lines of code' examples are inherently trying to be concise,
> and probably not the best things to learn from initially.
Even a Clojure expert would likely pause for a minute to figure out
what is going on in this code in the absence of any comments.
I still think there's a benefit in experienced Clojure developers
taking the extra effort to make their code more accessible to Clojure
newbies, especially if we want the community to grow.
Abhishek Reddy
had no intention of converting developers to Clojure, or of producing
instructive or readable code, with that snippet.
While I agree with some of your critique, I do think it is misplaced.
The aim of this particular exercise was to produce an _abnormally_
terse program, after all.
If you believe there is some utility in producing a more readable
version, as a tutorial, do not hesitate to make one and publish it!
I'll be happy to direct readers to it. :-)
Abhishek Reddy
http://abhishek.geek.nz
Emeka
Thanks so much for pointing that out, it makes Clojure to belong to others. Clojure should not be only for FP experts and PH.D holders. I took time to check the background of some members in this group: we have lecturers, research scientists and others from the best technical schools. I know that for such people simplifying(through commenting and spreading codes by using methods) Clojure may kill their brain "cells". But for me and other mere mortals we need such help and as I see Clojure it may become another phenomenon in the rank of Ruby.
Emeka
Itay Maman
"density": the ratio
of the "conceptual weight"of the computation to the size of the code
expressing it.
if a computation is inherently complicated and I manage to squeeze it
into
a few lines (typically accomplished via an intense cognitive effort)
the resulting
code is usually hard to understand/maintain/debug because you need to
be
acquainted with all sorts of little truths and insights which are not
obvious for the casual
reader. This is what I call a high density code.
Given that Clojure is a very powerful language, I often find my self
in a situation
where I mange to write highly dense code, sometimes at the expense of
readability. In such
cases I think that the use of explaining variables, and simplified-but-
somewhat-longer expressions
is desirable.
OTOH, if the code is inherently simple (e.g.: a chain of straight-
forward transformations on a collection)
I think that using Clojure's power to reduce the line count by a
factor of more than 5 (compared to, say, Java),
is highly beneficial.
The predicament is that there's no objective way to measure
"conceptual weight" nor "density" so
this issue is largely a personal judgment call.
Just my 2c.
--
Itay Maman
http://javadots.blogspot.com
Mark Volkmann
>
> Speaking for myself, as the author of the original Snake example, I
> had no intention of converting developers to Clojure, or of producing
> instructive or readable code, with that snippet.
>
> While I agree with some of your critique, I do think it is misplaced.
> The aim of this particular exercise was to produce an _abnormally_
> terse program, after all.
>
> If you believe there is some utility in producing a more readable
> version, as a tutorial, do not hesitate to make one and publish it!
> I'll be happy to direct readers to it. :-)
I apologize for the nature of my email which somewhat singled you out.
I would like to produce a version of the snake code that could serve
as an example of the kind of code that the Clojure community thinks is
"good". Unless it's part of an exercise to produce the shortest code
possible, I think we should always write Clojure code with a goal of
making it as easy as possible for others to read, while not attempting
to serve as a Clojure tutorial. Again, my goal here is to get more
developers to give Clojure a shot.
My challenge to everyone on the list is to start with any version of
the snake code you've seen and make it as readable as *you* think it
should be by doing things like renaming variables and functions,
adding comments and changing indentation. I'd really like to see what
*you* think is the best way to write this code. The lessons learned
from this exercise could then be applied to other code we write in the
future.
Mark Volkmann
<r.mark....@gmail.com> wrote:
> I would like to produce a version of the snake code that could serve
> as an example of the kind of code that the Clojure community thinks is
> "good". Unless it's part of an exercise to produce the shortest code
> possible, I think we should always write Clojure code with a goal of
> making it as easy as possible for others to read, while not attempting
> to serve as a Clojure tutorial. Again, my goal here is to get more
> developers to give Clojure a shot.
>
> My challenge to everyone on the list is to start with any version of
> the snake code you've seen and make it as readable as *you* think it
> should be by doing things like renaming variables and functions,
> adding comments and changing indentation. I'd really like to see what
> *you* think is the best way to write this code. The lessons learned
> from this exercise could then be applied to other code we write in the
> future.
Okay, I took the challenge and produced a modified version of my
earlier code where I removed what I considered to be redundant
comments and did a little more renaming. You can see it at
http://www.ociweb.com/mark/programming/ClojureSnake.html. Feedback is
welcomed!
I also started documenting some Clojure coding guidelines aimed at
making code more readable at
http://www.ociweb.com/mark/programming/ClojureCodingGuidelines.html
and would appreciate feedback on these. I expect there will be cases
where not following these is justified, which is why I refer to them
as guidelines instead of rules.
.Bill Smith
> the snake code you've seen and make it as readable as *you* think it
> should be by doing things like renaming variables and functions,
> adding comments and changing indentation. I'd really like to see what
> *you* think is the best way to write this code. The lessons learned
> from this exercise could then be applied to other code we write in the
> future.
snake code. I spent a few hours reading it, referring repeatedly to
the API documentation, renaming a few of the variables, experimenting
with snippets in REPL, and adding comments to the code so I wouldn't
forget what I'd learned. I'm not sure that's a problem, though. I
learned more in that process than I would have if the code had been
excruciatingly documented.
The level of "educational documentation" varies with the level of
experience. Too much documentation in an example is just as bad as
too little.
I also wonder whether insisting upon coding standards might deter
people from participating in this forum.
Bill
Matt Revelle
applicable to Clojure.
http://norvig.com/luv-slides.ps [PS]
http://www.cs.umd.edu/~nau/cmsc421/norvig-lisp-style.pdf [PDF]
lpetit
On 29 déc, 16:45, "Mark Volkmann" <r.mark.volkm...@gmail.com> wrote:
> On Mon, Dec 29, 2008 at 5:44 AM, Mark Volkmann
>
>
>
> <r.mark.volkm...@gmail.com> wrote:
> > I would like to produce a version of the snake code that could serve
> > as an example of the kind of code that the Clojure community thinks is
> > "good". Unless it's part of an exercise to produce the shortest code
> > possible, I think we should always write Clojure code with a goal of
> > making it as easy as possible for others to read, while not attempting
> > to serve as a Clojure tutorial. Again, my goal here is to get more
> > developers to give Clojure a shot.
>
> > My challenge to everyone on the list is to start with any version of
> > the snake code you've seen and make it as readable as *you* think it
> > should be by doing things like renaming variables and functions,
> > adding comments and changing indentation. I'd really like to see what
> > *you* think is the best way to write this code. The lessons learned
> > from this exercise could then be applied to other code we write in the
> > future.
>
> Okay, I took the challenge and produced a modified version of my
> earlier code where I removed what I considered to be redundant
>
> I also started documenting some Clojure coding guidelines aimed at
Randall R Schulz
> You should consider using docstrings for documenting functions
There's a big difference between the comments directed at someone
reading the code (possibly the author at a later date) and someone
wishing to use it. Function-level documentation strings serve only the
latter class of person.
Randall Schulz
Tom Ayerst
Generally, Clojure is a Lisp so Lisp idioms should apply (closing all your braces on the last line etc); you need to be thinking Lisp not Java, Ruby or whatever.
Tom Ayerst
Mark Volkmann
>
> You should consider using docstrings for documenting functions
I had forgotten to replace special characters with built-in entities
in my HTML, so that is fixed now. The new version is at
http://www.ociweb.com/mark/programming/ClojureSnake.html. What else
would you do different in this code? Do you think it still contains
too many comments?
Brian Doyle
Looking at this code the uppercase variables stands out.
This isn't idiomatic is it?
(def GRID_SIZE 10)
(def HEIGHT 600)
(def MARGIN 50)
Mark Volkmann
> Looking at this code the uppercase variables stands out.
> This isn't idiomatic is it?
>
> (def GRID_SIZE 10)
> (def HEIGHT 600)
> (def MARGIN 50)
uppercase. Is there a convention for this in Clojure? Is there a way I
could prevent them from being changed later? Maybe I should make them
be map entries where the keys are keywords and the values are the
integers. That seems extreme though.
Stuart Sierra
> > Looking at this code the uppercase variables stands out.
> > This isn't idiomatic is it?
>
> > (def GRID_SIZE 10)
> > (def HEIGHT 600)
> > (def MARGIN 50)
>
> I don't know. I was following Java conventions of making constants all
> uppercase. Is there a convention for this in Clojure?
There's a Common Lisp convention of surrounding constant names with
"+", like:
(def +grid-size+ 10)
but even in CL it's not followed consistently. Go with what feels
good. :)
> Is there a way I could prevent them from being changed later?
-Stuart Sierra
Chouser
<r.mark....@gmail.com> wrote:
>
> On Mon, Dec 29, 2008 at 2:24 PM, Brian Doyle <brian...@gmail.com> wrote:
>> Looking at this code the uppercase variables stands out.
>> This isn't idiomatic is it?
>>
>> (def GRID_SIZE 10)
>> (def HEIGHT 600)
>> (def MARGIN 50)
>
> I don't know.
I believe the idiom for global values like this is to place asterisks
around the name. Underscores (and CamelCase) should only be used when
required for Java interop:
(def *grid-size* 10)
(def *height* 600)
(def *margin* 50)
(def *x-index* 0)
(def *y-index* 1)
> I was following Java conventions of making constants all
> uppercase. Is there a convention for this in Clojure? Is there a way I
> could prevent them from being changed later?
I'm not aware of anyway to make a global constant. By using a Var as
you've done, the only way to change them is to use 'def' again (which
is a big hammer and very much discouraged inside regular functions) or
to use 'binding' to temporarily change their values within a
particular thread. I think what you have is sufficient for
communicating your intended meaning.
On a more general point, I'd personally recommend being wary of
over-investing in comments. This is not a radical recommendation, but
I'll bring up again anyway that thought that it's better to write code
in such a way that it explains itself than to add comments to code
that doesn't. Only when the former is insufficient should more
comments be added. Every line of comment is another line of code that
must be maintained, and worse than that it's a line that no compiler
or unit test is ever going to indicate as incorrect. When adding a
comment, I think it's appropriate to be sure that the maintenance cost
of the comment itself outweighs the maintenance cost of having no
comment (or a shorter or more general comment).
An example of this point -- Abhishek's original code used a hash
with:x and :y keys to indicate coordinates. I changed this to a
two-element vector only in pursuit of this particular puzzle's goals,
namely fewer lines of code. This is a very different goal from most
code, which should be maintainability, and also different from
tutorial code, which should be about teaching Clojure to someone who
doesn't already know it. For either of those latter goals, I would
contend Abhishek's solution was a better one -- using :x and :y help
indicate what's going on without global index names (like *x-index*)
or much extra commenting.
Another example -- if you find a particular use of #() to be too
confusing on its own, consider replacing it with a (fn ...), which
allows the naming of each argument as well as destructuring. This can
again improve readability without require more comments.
I think your expanded version of the snake program may be very
beneficial to some, though with a different purpose than the original
version, so thanks for providing it. Personally, I wouldn't want to
maintain a large codebase that was written using either style, as both
are a bit extreme in opposite ends of the verbosity scale. As I've
said elsewhere "golfing" is fun, if not broadly useful. Conversely,
tutorial-style code may be very useful in appropriate contexts, but is
hardly ever fun to write.
...and now this post is at an extreme of the verbosity scale. Sorry
all, I'll quit now before I get any further behind.
--Chouser
Mark Volkmann
Thanks for the info. Stuart!
It's early enough in the life of Clojure that we haven't developed any
deeply held habits yet. I think it would be a good idea for you and
other Clojure committers to at least suggest the way you think things
should be done in code. If you think surrounding names of constants
with plus signs is a good way to identify them as such, I'll gladly
start doing that for the sake of consistency. I don't think it's a
good idea for all of us to simply do what feels good because that will
make it harder to read code written by others.
Mark Volkmann
>
> On Mon, Dec 29, 2008 at 3:40 PM, Mark Volkmann
> <r.mark....@gmail.com> wrote:
>>
>> On Mon, Dec 29, 2008 at 2:24 PM, Brian Doyle <brian...@gmail.com> wrote:
>>> Looking at this code the uppercase variables stands out.
>>> This isn't idiomatic is it?
>>>
>>> (def GRID_SIZE 10)
>>> (def HEIGHT 600)
>>> (def MARGIN 50)
>>
>> I don't know.
>
> I believe the idiom for global values like this is to place asterisks
> around the name. Underscores (and CamelCase) should only be used when
> required for Java interop:
>
> (def *grid-size* 10)
> (def *height* 600)
> (def *margin* 50)
> (def *x-index* 0)
> (def *y-index* 1)
I think that's supposed to be + instead of *, at least Common Lisp
seems to use +.
> On a more general point, I'd personally recommend being wary of
> over-investing in comments. This is not a radical recommendation, but
> I'll bring up again anyway that thought that it's better to write code
> in such a way that it explains itself than to add comments to code
> that doesn't. Only when the former is insufficient should more
> comments be added.
I agree completely! In some programming languages, for example
Smalltalk, I feel like I can almost always write the code in a way
that doesn't require comments. However, I don't feel able to do that
as often in Clojure. I think it's because you can do so much with so
little code in Clojure. For example, here's some code that I don't
know how to rewrite in a way that I find self-explanatory:
(every?
#(<= (- (apple %) +grid-size+) (head %) (+ (apple %) +grid-size+))
[+x-index+ +y-index+]))
And here's another one:
(assoc snake :body
(cons
(vec (map #(+ (dir %) ((first body) %)) [+x-index+ +y-index+]))
(if grow body (butlast body)))))
Perhaps using your suggestion to go back and use a map with :x and :y
keys instead of a two-element vector to represent x/y coordinates
would help a little, but I'm still not sure the code would be
immediately obvious.
Maybe it's just a matter of time before I'm good enough at reading
Clojure code that I won't feel the need to add comments to these. Even
if that happens though, I'll still be concerned about the ability of
other developers that haven't yet reached that level of proficiency to
understand my code.
Chouser
<r.mark....@gmail.com> wrote:
>
> I think that's supposed to be + instead of *, at least Common Lisp
> seems to use +.
I meant * -- I don't know CL at all, but the *asterisk* form is used
frequently in clojure.core, while no +plus+ form ever appears. I also
was careful to refer to the global nature of the Vars, not anything
about const-ness.
--Chouser
Darren Austin
+ for constants (i.e. defconst) where * is used for global variables
(i.e. defparameter). In that case the + convention doesn't really
make sense in clojure as it doesn't have any notion of a constant
reference type.
--Darren
Mark Volkmann
Ah ... thanks for clarifying that! I've changed my code at
http://www.ociweb.com/mark/programming/ClojureSnake.html to follow
that convention.
Abhishek Reddy
Thanks for providing that. I've linked to it from the site of the
original post at http://www.plt1.com/1070/even-smaller-snake/
(Btw, a typo in my name at the top of your page :-)
Tom Ayerst
Mark H.
> It's early enough in the life of Clojure that we haven't developed any
> deeply held habits yet. I think it would be a good idea for you and
> other Clojure committers to at least suggest the way you think things
> should be done in code. If you think surrounding names of constants
> with plus signs is a good way to identify them as such, I'll gladly
> start doing that for the sake of consistency. I don't think it's a
> good idea for all of us to simply do what feels good because that will
> make it harder to read code written by others.
good or ill) is to treat such standards less like dogma and more like
gentle admonitions.
There does seem to be a little of a "culture clash" latent in this
discussion, between those with the "Lisp ethos" and those with the
"Java ethos." It has very little to do with naming conventions for
variables, and very much to do with the level of playfulness and
academic interest one has when approaching a new programming
language: do I ask, "ooo, how many lines of code do I need in order
to express this infinite data structure?" or "how do I get my Web 2.0
application up and running with the least effort?". Both of these are
good questions to ask: every serious computer science task needs both
application to motivate theory, and theory to improve existing
applications and inspire new ones. It's fun to see a language like
Clojure motivate both groups of people and get them talking -- Rich
has done great work in that respect by taking suggestions from both
groups and creating the space for them to interact.
It might be fun to make a list of books that folks on one side could
read to get the sense of how the other side thinks.
mfh
Christophe Grand
> For example, here's some code that I don't
> know how to rewrite in a way that I find self-explanatory:
>
> (every?
> #(<= (- (apple %) +grid-size+) (head %) (+ (apple %) +grid-size+))
> [+x-index+ +y-index+]))
>
> And here's another one:
>
> (assoc snake :body
> (cons
> (vec (map #(+ (dir %) ((first body) %)) [+x-index+ +y-index+]))
> (if grow body (butlast body)))))
>
> Perhaps using your suggestion to go back and use a map with :x and :y
> keys instead of a two-element vector to represent x/y coordinates
> would help a little, but I'm still not sure the code would be
> immediately obvious.
>
(every? #(<= (- *grid-size*) % *grid-size*)
(map - apple head)))
and
(assoc snake :body
(cons
(map + dir (first body))
(if grow body (butlast body)))))
and
(defn paint [graphics [x y] color]
(.setColor graphics color)
(.fillRect graphics x y *grid-size* *grid-size*))
As a bonus, it works with any number of dimensions :-)
Christophe
Mark Volkmann
>
> Mark Volkmann a écrit :
>> For example, here's some code that I don't
>> know how to rewrite in a way that I find self-explanatory:
>>
>> (every?
>> #(<= (- (apple %) +grid-size+) (head %) (+ (apple %) +grid-size+))
>> [+x-index+ +y-index+]))
>>
>> And here's another one:
>>
>> (assoc snake :body
>> (cons
>> (vec (map #(+ (dir %) ((first body) %)) [+x-index+ +y-index+]))
>> (if grow body (butlast body)))))
>>
>> Perhaps using your suggestion to go back and use a map with :x and :y
>> keys instead of a two-element vector to represent x/y coordinates
>> would help a little, but I'm still not sure the code would be
>> immediately obvious.
>>
> I think it would be clearer if we get rid of indexing:
>
> (every? #(<= (- *grid-size*) % *grid-size*)
> (map - apple head)))
>
> and
>
> (assoc snake :body
> (cons
> (map + dir (first body))
The previous line needs to be (vec (map + dir (first body))).
> (if grow body (butlast body)))))
>
> and
>
> (defn paint [graphics [x y] color]
> (.setColor graphics color)
> (.fillRect graphics x y *grid-size* *grid-size*))
Excellent improvements! Thank you very much!
I've updated http://www.ociweb.com/mark/programming/ClojureSnake.html
to include these changes.
> As a bonus, it works with any number of dimensions :-)
Except for the fact that Java's Graphics object doesn't know how to
paint in 3D. ;-)
Christophe Grand
>> (assoc snake :body
>> (cons
>> (map + dir (first body))
>>
>
> The previous line needs to be (vec (map + dir (first body))).
>
don't need to make a vector: a seq (or any collection type) is enough.
> Except for the fact that Java's Graphics object doesn't know how to
> paint in 3D. ;-)
Indeed. It works with n dimensions but you only see a 2D projection of
the play area :-(
Christophe
John D. Hume
> I believe the idiom for global values like this is to place asterisks
> around the name.
I thought the asterisk convention was for variables intended for
dynamic binding. It took me a minute to figure out where I got that
idea. "Programming Clojure" suggests it (without quite saying it) in
chapter 6, section 3.
"Vars intended for dynamic binding are sometimes called special vari-
ables. It is good style to name them with leading and trailing asterisks."
Obviously the book's a work in progress, but that does sound
reasonable. A special convention for variables whose values change (or
that my code's welcome to rebind) seems more useful to me than one for
"globals" (though I'm not sure I'd consider something like grid-size
for a given application a global). Based on ants.clj it appears Rich
doesn't feel there needs to be a special naming convention for that
sort of value.
What's your read on that, Chouser?
Mitch
like pylint for clojure with configurable rules, but which will
default to the standards agreed upon bu the clojure community. Even
if you don't follow the rules 100%, it could be useful to see where
you are deviating to be sure you really mean to in that situation.
Plus it'd be a good coding exercise.
-Mitch
Simon Brooke
> On Dec 28, 8:13 pm, "Mark Volkmann" <r.mark.volkm...@gmail.com> wrote:
>
> I'll not argue for making code harder to read, but I have to object to
> most of your example.
>
> Making something 4x longer does not make it easier to read.
>
> Redundant comments are useless.
This is the excuse continually trotted out by people too lazy to
comment, or who think themselves superior to merely mortal programmers
who have to work in teams and actually communicate with people.
Redundancy in communication is almost never redundant; think of it as
a checksum. When you listen to someone talking naturally and
explaining something, you'll almost always find they express the same
idea multiple times in different forms of words. Why? It makes certain
that it is clear.
I'm not denying there are occasions where comments add nothing to the
reader's understanding of the code. But they are usually not cases
where the comment repeats (in English or some other natural language)
what is being expressed in Lisp or Java or XSLT or whatever.
Repetition is not in itself bad. On the contrary, it can be explicitly
good, because places where what's written in the comment describes
something different from what's described in the code are probably
places for bugs.
I've never, in my life, worked with another programmer who commented
too much. I've once in my life worked with another programmer who
commented enough. In my experience, if you take over someone else's
code either to maintain it or to integrate it or to reuse components
from it, you're normally in for a huge learning process which would
have been obviated simply by adequate commenting.
'Redundant comments are useless' is the mantra of the dilettante, the
amateur, and the cowboy.
Rich Hickey
On Dec 31, 9:42 am, Simon Brooke <still...@googlemail.com> wrote:
> On Dec 29, 3:15 am, Rich Hickey <richhic...@gmail.com> wrote:
>
> > On Dec 28, 8:13 pm, "Mark Volkmann" <r.mark.volkm...@gmail.com> wrote:
>
> > I'll not argue for making code harder to read, but I have to object to
> > most of your example.
>
> > Making something 4x longer does not make it easier to read.
>
> > Redundant comments are useless.
>
> This is the excuse continually trotted out by people too lazy to
> comment, or who think themselves superior to merely mortal programmers
> who have to work in teams and actually communicate with people.
> amateur, and the cowboy.
please spare us the pejoratives.
Thanks,
Rich
Tom Ayerst
Having said that; redundancy is a matter of context and I could use more comments and meaningful variables in example code, I am acquainted with Scheme so I can work my way through, but it is easy to get lost in the homogeneous syntax and unfamiliar constructs and idioms.
When trying something new the fewer gumption traps the better and it is important to make sure information is to hand, this could be done through repetition or by the application of a little more indirection; earlier in the thread Mark asked if people would be aware of how to set up a clj script, good question and a link to the place that explains how, when you need it, would be very useful.
Personally I don't think we need standards and stuff, what we need is some more "code with training wheels" (lots comments and links taking you through it very gently). That is not really Rich's job, he is to busy inventing the thing, I think Mark's evolving example is great and a few more like it covering other areas would be fine things and I hope to add to them myself when I am a bit more familiar with Clojure.
That was a bit more rambling than planned.
Happy New Year
Tom
On Dec 29, 3:15 am, Rich Hickey <richhic...@gmail.com> wrote:
> On Dec 28, 8:13 pm, "Mark Volkmann" <r.mark.volkm...@gmail.com> wrote:
>
> I'll not argue for making code harder to read, but I have to object toThis is the excuse continually trotted out by people too lazy to
> most of your example.
>
> Making something 4x longer does not make it easier to read.
>
> Redundant comments are useless.
comment, or who think themselves superior to merely mortal programmers
who have to work in teams and actually communicate with people.
Redundancy in communication is almost never redundant; think of it as
a checksum.
...
Weiqi Gao
> On Dec 29, 3:15 am, Rich Hickey <richhic...@gmail.com> wrote:
>> On Dec 28, 8:13 pm, "Mark Volkmann" <r.mark.volkm...@gmail.com> wrote:
>>
>
>> I'll not argue for making code harder to read, but I have to object to
>> most of your example.
>>
>> Making something 4x longer does not make it easier to read.
>>
>> Redundant comments are useless.
>
> This is the excuse continually trotted out by people too lazy to
> comment, or who think themselves superior to merely mortal programmers
> who have to work in teams and actually communicate with people.
I used to subscribe to this thought. Now I don't.
I used to put useless comments in my code. Now I don't.
Comments should be appropriate to the persons who will read it. Copious
comments are appropriate in tutorials and SDK examples, etc. But for
production code, I'll comment only if I feel that *I* will need it when
I come back to the code later.
I do not think I'm superior to anybody else. But a certain level of
competence is assumed in any project. My assumption is that after I'm
gone from a project, whoever replaces me should be at least as competent
as I am. If not, that's not my problem.
> Redundancy in communication is almost never redundant; think of it as
> a checksum. When you listen to someone talking naturally and
> explaining something, you'll almost always find they express the same
> idea multiple times in different forms of words. Why? It makes certain
> that it is clear.
There is a difference between code and other forms of communication. If
the code is not clear, sure, add comments. But why write code that's
not clear?
> I'm not denying there are occasions where comments add nothing to the
> reader's understanding of the code. But they are usually not cases
> where the comment repeats (in English or some other natural language)
> what is being expressed in Lisp or Java or XSLT or whatever.
> Repetition is not in itself bad. On the contrary, it can be explicitly
> good, because places where what's written in the comment describes
> something different from what's described in the code are probably
> places for bugs.
It's a bug for sure. The wrong comment should simply be deleted.
> I've never, in my life, worked with another programmer who commented
> too much.
I myself commented too much when I was less experienced. My comments
were ridiculous and harmed the understanding of the actual code.
> I've once in my life worked with another programmer who
> commented enough. In my experience, if you take over someone else's
> code either to maintain it or to integrate it or to reuse components
> from it, you're normally in for a huge learning process which would
> have been obviated simply by adequate commenting.
If you don't understand a piece of code, with comments or without
comments, you should not touch it.
There's a learning curve when you take over a piece of code, comments or
no comments, period.
> 'Redundant comments are useless' is the mantra of the dilettante, the
> amateur, and the cowboy.
... and the true professional. Telling which is which is the job of the
hiring manager.
I guess if you are the hiring manager, you wouldn't hire me. I'll work
for your competitor, where codes are strong, comments are lean, and
every one is above average. :)
[For the humor impaired, the last sentence is meant to be a joke. A joke
is something that is supposed to be funny. Funny things should make you
laugh. And laugh is the act where your facial muscles move in a certain
way as to effect a configuration of your face where the corner of your
mouth rises above the center of your mouth. This paragraph is also an
example of over-the-board commenting.]
--
Weiqi Gao
weiq...@gmail.com
http://www.weiqigao.com/blog/
Mark Volkmann
first code snippet at http://clojure.org/concurrent_programming.
(import '(java.util.concurrent Executors))
(defn test-stm [nitems nthreads niters]
(let [refs (map ref (replicate nitems 0))
pool (. Executors (newFixedThreadPool nthreads))
tasks (map (fn [t]
(fn []
(dotimes [n niters]
(dosync
(doseq [r refs]
(alter r + 1 t))))))
(range nthreads))]
(doseq [future (. pool (invokeAll tasks))]
(. future (get)))
(. pool (shutdown))
(map deref refs)))
Many people new to Clojure will be attracted to this page because they
will have heard that one of the strengths of Clojure is how good it is
for concurrent programming.
I believe the purpose of this example is to demonstrate how much
easier it is to program with Clojure refs instead of Java locks.
Certainly this code is much shorter than similar Java code. There is a
paragraph before the code that explains what the code does and there
are no comments within the code.
Suppose you had been studying Clojure for one week before coming
across this code. Would you know what was going on here? Let's see ...
we've got an anonymous function that uses an anonymous function which
iterates some number of times calling dosync on a doseq ... alter
changes the value of a ref ... it uses a future ... My fear is that
many developers will become discouraged and stop trying to learn
Clojure, fearing that it's just too hard. I think we need to work to
minimize those kinds of reactions to sample code. Adding some comments
to non-obvious code is one way to do that.
I don't mean to single out this one example. Many examples of Clojure
code seem equally daunting to me and most Clojure code seems to
contain no comments at all.
Daniel Eklund
> comment, or who think themselves superior to merely mortal programmers
> who have to work in teams and actually communicate with people.
> Redundancy in communication is almost never redundant; think of it as
A checksum should be trusted. Comments sometimes cannot.
Since you brought up the issue with working in teams, I will submit my
decade and a half of experience coding in 'enterprise' team
environments (my chosen hell). I have built upon and maintained Java
code that has grown through accretion of various consulting
organizations, and I never trust comments. Even with third party
(supposedly stable) APIs, I have had (more than once) to open up the
code to discover that the javadocs are out of date and incorrect. I
do my bit; I try to maintain my comments, but I never trust. The code
IS the answer, always.
> 'Redundant comments are useless' is the mantra of the dilettante, the
> amateur, and the cowboy.
'redundant comments are useless'. If not, what about the phrase
'useless comments are useless'?
Mark H.
> Suppose you had been studying Clojure for one week before coming
> across this code. Would you know what was going on here? Let's see ...
> we've got an anonymous function that uses an anonymous function which
> iterates some number of times calling dosync on a doseq ... alter
> changes the value of a ref ... it uses a future ... My fear is that
> many developers will become discouraged and stop trying to learn
> Clojure, fearing that it's just too hard. I think we need to work to
> minimize those kinds of reactions to sample code. Adding some comments
> to non-obvious code is one way to do that.
example is having that effect. Maybe the right thing to do is to
point to the "ants" demo or some demo which accomplishes an
interesting task? The trouble is, it's hard to come up with
meaningful concurrent code that fits on a single web page ;-)
> I don't mean to single out this one example. Many examples of Clojure
> code seem equally daunting to me and most Clojure code seems to
> contain no comments at all.
mfh
Luc Prefontaine
Comments are worse since Javadoc came to life, up to date or not.
Most of the time they do not describe the behaviour of the class in depth and you have to get the source code
on your screen.
We replaced quality by quantity. If I want to find the signature of a function I can always read the code,
assuming I have access to it of course.
I would expect much more from Javadoc than class fields and member function signatures but this would require
discipline from dev people to add significant and useful comments in their code.
Javadoc is an evil tool, it gives the impression that your system is documented because it easily spits out
garbage... but it's only garbage, not worth anything when you're trying to fix a problem that requires
a broader knowledge than the 25 code lines scope on your screen.
In the mid 80's I and others in a Fortran dev. team created a super javadoc. This beast was spitting out a FULL
document in the editor used by office people.
You would write comments in the code that were extracted and you would get a readable well formatted
document after running the tool. Without the comments, the document looked ... empty and ugly.
Missing items were as obvious as a nose in a face.
Easier for code reviewer to control that, no need to read the code, read the document. If it does not make sense
then go back to the coder.
Coders had to add decent comments since the conventions were not only based on what you extract from the code
(like javadoc) but also what is expected in comments so the document text content gets filled with decent content.
When you force the coder to enter comments to fil a chapter introduction, well he/she has no choice.
Of course it looks like if creating code is twice as complex but in fact you saved time when you need a system to be
described very precisely. It also insured that comments were meaningful and in synch. with the code.
If no decent comments are added in the code, then were is the knowledge and how can it be shared ?
After 20 years of dev, I dropped javadoc entirely, comments are now minimal (function description, oddities in the code)
and I COMPENSATE with external doc (a real document). Why should I bother to get clear documentation in the code since
most of the world out there does not care about it ? Best proof, almost nobody does it these days.
External doc at least gives an explanation of the design and structure. It does not even have to be fully in synch with
the code. Even outdated it is a better starting point for someone to learn how to navigate in application internals.
You get a sense of what the designers wanted to achieve and how. Then when you get to code, it's much more
easier because you have a broader picture and can make sense of what you are reading.
You can review it once every year and that's enough. Most of the time you already have some basic material about the
things that changed or were added. It's just a matter of reorganizing it.
I fully agree ultimately code is the thing that runs... not your comments or your documentation.
Many people still speculate about system behaviour from the comments they read and eventually derive
plans from this. Bad mistake... go to the code for your own sake.
Luc
Joseph Jones
On Dec 31, 2008, at 1:29 PM, Luc Prefontaine wrote:
> In the mid 80's I and others in a Fortran dev. team created a super
> javadoc. This beast was spitting out a FULL
> document in the editor used by office people.
>
> You would write comments in the code that were extracted and you
> would get a readable well formatted
> document after running the tool. Without the comments, the document
> looked ... empty and ugly.
> Missing items were as obvious as a nose in a face.
>
> Easier for code reviewer to control that, no need to read the code,
> read the document. If it does not make sense
> then go back to the coder.
>
> Coders had to add decent comments since the conventions were not
> only based on what you extract from the code
> (like javadoc) but also what is expected in comments so the document
> text content gets filled with decent content.
> When you force the coder to enter comments to fil a chapter
> introduction, well he/she has no choice.
>
> Of course it looks like if creating code is twice as complex but in
> fact you saved time when you need a system to be
> described very precisely. It also insured that comments were
> meaningful and in synch. with the code.
>
That sounds a LOT like Knuth's Literate Programming. Was there
influence from that or was this wholly based non your own?
joe
Luc Prefontaine
were required to spit out detailed specs at every release.
This was a real-time redundant system to control production and transportation of electricity in the province of Quebec.
That system had to show up 99.9999% availability.
We have a vast network here, a single utility and the production sites
(up north in the James Bay area ) are far from the consumers (mostly south near the St-Lawrence
river). The software to control this as to be resilient otherwise the whole network can
come down even if the network control is distributed in several centres.
The idea of "duplicating" the content of the code in a document seemed to us a waste of time
and money. So we came out with this tool. We had a significant number of modules to add
to the existing system and many modifications to existing modules.
Saved us many hours of document editing, reviewing and so on. It proved very efficient.
Of course the requirement of having detailed documentation is not always present
in most systems. But this one being critical, that requirement was unavoidable.
Maybe I should look back at this and see how I could revive it. I used to comment heavily my code
in my first ten years or so. I wrote a number of systems in assembly languages (20,000 to 40,000 lines)
and it's quite natural to add comments when programming systems of that magnitude.
I kept this habit for a long time even in high level languages or not so high level (C).
Maybe I should experiment again and see if it's worthwhile.
I was rather pissed off by the lacklustre of javadoc, especially when you need to add html tags to get some decent output.
Our tools did not need any formatting hints. That was handled when calling the tool. The tags we used
were there to indicate the sections forming the document, not the way they were to be presented.
They were simple tags inserted at the beginning of a comment line.
You could change the rendering of the document when calling the tool.
That idea came from SGML that we were using at the time, WYSIWYG was just around the corner but we still had to typeset
our documents using SGML tags. With SGML you postpone the presentation issues were they belong, when rendering the document
on your laser printer or other rendering device.
I may dedicate some time to this. Of course it has to be adapted to the languages used today and coders have to show
some willingness to add significant comments to their code. If people are reluctant to do this then such a tool does not
have any future :))))
Luc
Hugh Winkler
post that definitely takes a stand on the commenting issue:
http://steve-yegge.blogspot.com/2008/02/portrait-of-n00b.html
As usual with Steve, it's a funny post, so I hope nobody takes it too
seriously :)
Hugh
Luc Prefontaine
The amount of comments is difficult to balance and yes as you get more experience, you'd rather cram
as much code lines in a screen shot as possible. 0 comments ? No that's not good. The other extreme he shows
is also not viable. If maintaining the comments takes as much time as maintaining the code, productivity
will inevitably suffer.
We need to find a balance; short function synopsis, critical code section comments, ...
These should be the basis from which we write comments and should be readable without the code so
you get a minimal comprehension of what the code does without having to read the code entirely.
It does not mean however that it should replace the code when looking for the details.
Anything else that transcends the code modules should be in an external document.
The other subject of Steve's post is much more important than the part about comments.
He's absolutely right about meta data overkill... and there's nothing funny about it when you look at the overall situation.
If I look back at the Java code my team wrote in the last 4 years, there is less
human generated code lines than meta data configuration lines and generated code lines from this meta data.
Typically written in XML which is so cumbersome that you need a schema sensitive editor to create valid files...
A task by itself that has nothing to do with coding. Are these XML configuration files really self describing ?
The number of frameworks out there with their specific configuration weirdness makes transitions from one to the other at best awkward.
As soon as you hit a major bug or want to do something that is not supported or does not fit in a framework you're left nude on the
ice bank. If you have invested heavily in configuration files and not in the code so your options are limited and require significant investments.
In the life of a project, it's not good...
At least if you are using code libraries you can modify the code locally to circumvent the problem. With frameworks it's
much more complicated to do, do you have access to the code ? Do you have resources to fix the issue without compromising the
framework ? What about maintenance ? Can you expect your fix to make it in the next release or is it too specific to your
project to ever make it in the general code base ?.... All these options are far from fixing a limited code chunk in a library.
People have been less and less polyvalent in the last 10 years. Those lucky enough to work deep enough
with different technologies should make sure they keep that skill and open mind. I feel things will eventually change
because the industry track record has not improved at all with this bureaucratic approach to software.
The industry tried to replace intelligence (coders creating effective code) by some fabrication process driven by robots (writing
endless configuration lines to generate code, specify behaviour, ...) while the anarchitects and DBA model the universe
down to the atoms...
Meanwhile the project time lines and budgets are busted and the pertinence of the code delivered drops.
I've seen projects where intensive modelling made the performance so unbearable that some extra time was added
at the end of the project to get rid of some of the modelling to get back some performance.
Some of these projects were killed because there was no way you could retool them to remove the performance
bottlenecks without redoing the project.
Too much modelling kills but it does not mean that you do not need a model, you have to know when to stop.
But that's out of reach for most of the model addicts out there.
You do not need a modelling tool to built a flexible model, you need a minimal set of rules to which your system should stick to avoid failures.
The industry replaced this common sense by these heavy tools that created the trend that you should model everything to ensure the code is "right".
Tools like Rationale are the worst, they pretend that you can create code from a model without hand crafting the code...
I've seen code generated by these tools and it's basically unreadable. Things are broke down to 10 lines classes, there is no way you can
really understand the code except if you understand fully the model and hence what the modeler had in mind.
The industry has been seeking the Holy Graal to replace the coder by some formal bureaucratic process since the end of 1970's
and what we have seen in the last 10 years is another failure to reach that goal. Bureaucracy cannot replace intelligence.
We see this in our respective governments and how they "manage" public services so why would we expect a better outcome
in creating software the same way ?
Is this thread unpleasant ? Looking at the world without pink glasses is not funny but taking the time to understand
things gives you a sense of where we come from and where we might be going.
As for Steve's post, it's about serious matters.
Nonetheless, have a Happy New Year :))) and sorry for the heavy post...
Luc