Re: making code readable
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
Re: making code readable
I hesitate to extend this unpleasant thread, but here's a relevant 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 On Wed, Dec 31, 2008 at 9:49 AM, Tom Ayerst wrote: > "'Redundant comments are useless' is the mantra of the dilettante, the > amateur, and the cowboy."dilettante, the amateur, and the cowboy"", ouch. > Redundant comments are... redundant (hence the name), and a support overhead > and a source of misunderstanding if they are not updated in line with the > code. If you are writing code that will be read by people familiar with the > language and idioms and using meaningful names then a small number well > targeted comments are usually enough (Personally I do like a comment on each > function saying what it is for, doc strings look like the right solution for > this). > > 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 > > 2008/12/31 Simon Brooke >> >> On Dec 29, 3:15 am, Rich Hickey wrote: >> > On Dec 28, 8:13 pm, "Mark Volkmann" 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. >> >> ... >> >> 'Redundant comments are useless' is the mantra of the dilettante, the >> amateur, and the cowboy. >> > > > > > --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
It was our own initiative. 4 of us integrated an existing team of developers and they 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.% 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 On Wed, 2008-12-31 at 17:23 -0800, Joseph Jones wrote: > > 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 > > > > > --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
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 --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
My two cents... 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 On Wed, 2008-12-31 at 08:41 -0800, Daniel Eklund wrote: > > 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. > > 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. > > I believe the मन्त्र 'comments are useless' is more cowboy-like, not > 'redundant comments are useless'. If not, what about the phrase > 'useless comments are useless'? > > > --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
On Dec 31, 8:13 am, "Mark Volkmann" wrote: > 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. The misfortune is that a code which is pretty much just an academic 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. Just wait until you see mine ;-P (It's practically an essay.) mfh --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
> 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. 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. I believe the मन्त्र 'comments are useless' is more cowboy-like, not 'redundant comments are useless'. If not, what about the phrase 'useless comments are useless'? --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
I'd like to focus the attention back to a specific example. See the 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. -- R. Mark Volkmann Object Computing, Inc. --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
Simon Brooke wrote: > On Dec 29, 3:15 am, Rich Hickey wrote: >> On Dec 28, 8:13 pm, "Mark Volkmann" 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 weiqi...@gmail.com http://www.weiqigao.com/blog/ --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
"'Redundant comments are useless' is the mantra of the dilettante, the amateur, and the cowboy."dilettante, the amateur, and the cowboy"", ouch. Redundant comments are... redundant (hence the name), and a support overhead and a source of misunderstanding if they are not updated in line with the code. If you are writing code that will be read by people familiar with the language and idioms and using meaningful names then a small number well targeted comments are usually enough (Personally I do like a comment on each function saying what it is for, doc strings look like the right solution for this). 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 2008/12/31 Simon Brooke > > On Dec 29, 3:15 am, Rich Hickey wrote: > > On Dec 28, 8:13 pm, "Mark Volkmann" 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. > > ... > > 'Redundant comments are useless' is the mantra of the dilettante, the > amateur, and the cowboy. > > --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
On Dec 31, 9:42 am, Simon Brooke wrote: > On Dec 29, 3:15 am, Rich Hickey wrote: > > > On Dec 28, 8:13 pm, "Mark Volkmann" 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. > 'Redundant comments are useless' is the mantra of the dilettante, the > amateur, and the cowboy. You're free to hold whatever opinions you like, but on this list please spare us the pejoratives. Thanks, Rich --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
On Dec 29, 3:15 am, Rich Hickey wrote: > On Dec 28, 8:13 pm, "Mark Volkmann" 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. --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
What about some sort of lint program? I'm thinking about something 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 On Dec 30, 12:50 am, "Mark H." wrote: > On Dec 29, 1:15 pm, "Mark Volkmann" wrote: > > > 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. > > Indeed, standards are good, but I do think part of the "Lisp way" (for > 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 --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
On Mon, Dec 29, 2008 at 4:10 PM, Chouser wrote: > 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? --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
Mark Volkmann a écrit : >> (assoc snake :body >>(cons >> (map + dir (first body)) >> > > The previous line needs to be (vec (map + dir (first body))). > It works without the vec. Since we aren't using indexing anymore we 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 --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
On Tue, Dec 30, 2008 at 4:21 AM, Christophe Grand wrote: > > 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. ;-) -- R. Mark Volkmann Object Computing, Inc. --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
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)) (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 --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
On Dec 29, 1:15 pm, "Mark Volkmann" wrote: > 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. Indeed, standards are good, but I do think part of the "Lisp way" (for 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 --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
A useful comment addition: How do I run it? Cheers Tom 2008/12/29 Mark Volkmann > > On Mon, Dec 29, 2008 at 3:58 PM, Chouser wrote: > > > > On Mon, Dec 29, 2008 at 4:40 PM, Mark Volkmann > > 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. > > Ah ... thanks for clarifying that! I've changed my code at > http://www.ociweb.com/mark/programming/ClojureSnake.html to follow > that convention. > > -- > R. Mark Volkmann > Object Computing, Inc. > > > > --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
Mark, 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 :-) On 12/30/08, Mark Volkmann wrote: > > On Mon, Dec 29, 2008 at 3:58 PM, Chouser wrote: >> >> On Mon, Dec 29, 2008 at 4:40 PM, Mark Volkmann >> 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. > > Ah ... thanks for clarifying that! I've changed my code at > http://www.ociweb.com/mark/programming/ClojureSnake.html to follow > that convention. > > -- > R. Mark Volkmann > Object Computing, Inc. > > > > -- Abhishek Reddy http://abhishek.geek.nz --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
On Mon, Dec 29, 2008 at 3:58 PM, Chouser wrote: > > On Mon, Dec 29, 2008 at 4:40 PM, Mark Volkmann > 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. Ah ... thanks for clarifying that! I've changed my code at http://www.ociweb.com/mark/programming/ClojureSnake.html to follow that convention. -- R. Mark Volkmann Object Computing, Inc. --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
I don't know CL that well myself, but I think the convention is to use + 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 On Mon, Dec 29, 2008 at 1:58 PM, Chouser wrote: > > On Mon, Dec 29, 2008 at 4:40 PM, Mark Volkmann > 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 > > > > --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
On Mon, Dec 29, 2008 at 4:40 PM, Mark Volkmann 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 --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
On Mon, Dec 29, 2008 at 3:10 PM, Chouser wrote: > > On Mon, Dec 29, 2008 at 3:40 PM, Mark Volkmann > wrote: >> >> On Mon, Dec 29, 2008 at 2:24 PM, Brian Doyle 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. -- R. Mark Volkmann Object Computing, Inc. --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
On Mon, Dec 29, 2008 at 3:01 PM, Stuart Sierra wrote: > > On Dec 29, 3:40 pm, "Mark Volkmann" wrote: >> On Mon, Dec 29, 2008 at 2:24 PM, Brian Doyle 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 was following Java conventions of making constants all >> uppercase. Is there a convention for this in Clojure? > > Hi Mark, > > 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? > > Not really, you can always re-def. 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. -- R. Mark Volkmann Object Computing, Inc. --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
On Mon, Dec 29, 2008 at 3:40 PM, Mark Volkmann wrote: > > On Mon, Dec 29, 2008 at 2:24 PM, Brian Doyle 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 --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
On Dec 29, 3:40 pm, "Mark Volkmann" wrote: > On Mon, Dec 29, 2008 at 2:24 PM, Brian Doyle 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 was following Java conventions of making constants all > uppercase. Is there a convention for this in Clojure? Hi Mark, 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? Not really, you can always re-def. -Stuart Sierra --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
On Mon, Dec 29, 2008 at 2:24 PM, Brian Doyle 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 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? Maybe I should make them be map entries where the keys are keywords and the values are the integers. That seems extreme though. > On Mon, Dec 29, 2008 at 12:19 PM, Mark Volkmann > wrote: >> >> On Mon, Dec 29, 2008 at 11:11 AM, lpetit wrote: >> > >> > You should consider using docstrings for documenting functions >> >> Good suggestion. I've changed my code to do that. I also noticed that >> 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? >> >> > On 29 déc, 16:45, "Mark Volkmann" wrote: >> >> On Mon, Dec 29, 2008 at 5:44 AM, Mark Volkmann >> >> >> >> >> >> >> >> 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 >> >> athttp://www.ociweb.com/mark/programming/ClojureSnake.html. Feedback is >> >> welcomed! >> >> >> >> I also started documenting some Clojure coding guidelines aimed at >> >> making code more readable >> >> athttp://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. >> >> >> >> -- >> >> R. Mark Volkmann >> >> Object Computing, Inc. >> > > >> > >> >> >> >> -- >> R. Mark Volkmann >> Object Computing, Inc. >> >> > > > > > -- R. Mark Volkmann Object Computing, Inc. --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
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) On Mon, Dec 29, 2008 at 12:19 PM, Mark Volkmann wrote: > > On Mon, Dec 29, 2008 at 11:11 AM, lpetit wrote: > > > > You should consider using docstrings for documenting functions > > Good suggestion. I've changed my code to do that. I also noticed that > 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? > > > On 29 déc, 16:45, "Mark Volkmann" wrote: > >> On Mon, Dec 29, 2008 at 5:44 AM, Mark Volkmann > >> > >> > >> > >> 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 athttp:// > www.ociweb.com/mark/programming/ClojureSnake.html. Feedback is > >> welcomed! > >> > >> I also started documenting some Clojure coding guidelines aimed at > >> making code more readable athttp:// > 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. > >> > >> -- > >> R. Mark Volkmann > >> Object Computing, Inc. > > > > > > > > > -- > R. Mark Volkmann > Object Computing, Inc. > > > > --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
On Mon, Dec 29, 2008 at 11:11 AM, lpetit wrote: > > You should consider using docstrings for documenting functions Good suggestion. I've changed my code to do that. I also noticed that 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? > On 29 déc, 16:45, "Mark Volkmann" wrote: >> On Mon, Dec 29, 2008 at 5:44 AM, Mark Volkmann >> >> >> >> 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 >> athttp://www.ociweb.com/mark/programming/ClojureSnake.html. Feedback is >> welcomed! >> >> I also started documenting some Clojure coding guidelines aimed at >> making code more readable >> athttp://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. >> >> -- >> R. Mark Volkmann >> Object Computing, Inc. > > > -- R. Mark Volkmann Object Computing, Inc. --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
Not sure about that; knowing what a function is for is an important starting point to understanding it. Anyway' half of the code you work on will be using the other half (for given values of 'half' of course ;-) . 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 2008/12/29 Randall R Schulz > > On Monday 29 December 2008 09:11, lpetit wrote: > > 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 > > > > --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
On Monday 29 December 2008 09:11, lpetit wrote: > 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 --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
You should consider using docstrings for documenting functions On 29 déc, 16:45, "Mark Volkmann" wrote: > On Mon, Dec 29, 2008 at 5:44 AM, Mark Volkmann > > > > 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 > athttp://www.ociweb.com/mark/programming/ClojureSnake.html. Feedback is > welcomed! > > I also started documenting some Clojure coding guidelines aimed at > making code more readable > athttp://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. > > -- > R. Mark Volkmann > Object Computing, Inc. --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
On Dec 29, 2008, at 10:45 AM, Mark Volkmann wrote: > > On Mon, Dec 29, 2008 at 5:44 AM, Mark Volkmann > 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. Much of Norvig's "Tutorial on Good Lisp Programming Style" is applicable to Clojure. http://norvig.com/luv-slides.ps[PS] http://www.cs.umd.edu/~nau/cmsc421/norvig-lisp-style.pdf[PDF] > > > -- > R. Mark Volkmann > Object Computing, Inc. > > > --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
> 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. I'll keep this as short. Thanks to the folks who contributed to the 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 --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
On Mon, Dec 29, 2008 at 5:44 AM, Mark Volkmann 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. -- R. Mark Volkmann Object Computing, Inc. --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
On Mon, Dec 29, 2008 at 12:03 AM, Abhishek Reddy wrote: > > 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. -- R. Mark Volkmann Object Computing, Inc. --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
I think that just as important as "compactness" is the issue of "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 --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
Mark, 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 --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: making code readable
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. :-) On 12/29/08, Mark Volkmann wrote: > > On Sun, Dec 28, 2008 at 9:15 PM, Rich Hickey wrote: >> >> On Dec 28, 8:13 pm, "Mark Volkmann" wrote: >>> This is related to the thread titled "Proxying in Clojure". I've spent >>> 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 >>> athttp://pastie.org/348031where 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] [] >>> >>> (paintCompon
Re: making code readable
On Sun, Dec 28, 2008 at 9:15 PM, Rich Hickey wrote: > > On Dec 28, 8:13 pm, "Mark Volkmann" wrote: >> This is related to the thread titled "Proxying in Clojure". I've spent >> 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 >> athttp://pastie.org/348031where 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]
Re: making code readable
On Dec 28, 8:13 pm, "Mark Volkmann" wrote: > This is related to the thread titled "Proxying in Clojure". I've spent > 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 > athttp://pastie.org/348031where 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
making code readable
This is related to the thread titled "Proxying in Clojure". I've spent 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