On Wed, Sep 8, 2010 at 12:05 AM, Sean Corfield <seancorfi...@gmail.com> wrote: > Most people who read my code have said it reads like poetry...
Poetry takes a complex message and packs it into as few words as possible, resulting in something so cryptic and enigmatic that people bicker endlessly about what subtle meanings the author really intended. I don't know that I'd be flattered by that comparison :) If you ever read an article presenting some new algorithm, data structure, etc. in an academic journal, the published article will certainly contain some actual prose describing what's going on. Code does not, in general, speak for itself (although good code with good naming conventions can certainly be understood by people who use the same conventions and understand the underlying problem and solution approach as well as you do). If code did speak for itself, these journal articles would just be big hunks of code. Now that's dealing with documentation on the level of understanding the code implementation itself. But even API documentation varies considerably in terms of scope and complexity. The Flash API documentation is very well written and it fills two 600+-page volumes. Racket has done a very nice job of documenting the language and the libraries. As I understand it, their team of developers spent nearly a year working primarily on documentation rather than new features. Most features are explained in two separate documents: a "guide" that explains the gist of how a certain library works, and a "reference" that provides the API details. Both documents are extremely useful. The guide is something you can read cover to cover to feel like you really understand what the system is capable of. The reference is something where you can look up specific issues. On the spectrum between "self-documenting code" and Knuth's "literate programming", my personal preference is something about two-thirds of the way towards Knuth. It's always hard to find time to document code, and documenting code that is heavily in flux can potentially be a waste of time, but ideally, I think that spending 20% of one's time on documentation is a good target to aim for. Our preferences are shaped by our experiences, of course, and your mileage may vary. What is the largest body of code you've tried to read and understand and maintain? Were you able to talk with developers about the code, or did you just have to understand it by reading it? What things did you like and dislike about the readability of their code? My experience aligns well with the points raised in this essay (see http://www.joelonsoftware.com/articles/fog0000000069.html for the full article): "There's a subtle reason that programmers always want to throw away the code and start over. The reason is that they think the old code is a mess. And here is the interesting observation: they are probably wrong. The reason that they think the old code is a mess is because of a cardinal, fundamental law of programming: It’s harder to read code than to write it. This is why code reuse is so hard. This is why everybody on your team has a different function they like to use for splitting strings into arrays of strings. They write their own function because it's easier and more fun than figuring out how the old function works." I agree that it is harder to read code than to write it and that readability is the #1 obstacle to code reuse, so I feel an obligation to tilt the balance a bit more in favor of the reader. I think just about our only point of agreement is that I also feel that it is difficult to maintain documentation that is separate from the code. That's why I'm always on the lookout for new tools and techniques to make that process easier. -- 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 Note that posts from new members are moderated - please be patient with your first post. 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
