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