Howdy Tim,
On Thu, May 22, 2014 at 1:16 AM, u1204 <d...@axiom-developer.org> wrote:
> Gregg and Gary,
>
> I understand where you are coming from. Indeed, Maturana [0] is on your
> side of the debate. Since even the philosophers can't agree, I doubt we
> will find a common ground.
>
Ah, but philosophers never agree. Disagreement is part of their job
description. Why should programmers be any different?
>
> Unfortunately, I've decided to take on the task of documenting the
> Clojure internals because, yaknow, *I* don't feel I understand something
> until I know what the hardware does; consider this a flaw in my
> personality :-)
I suffer from a similar malady, which compels me to continually rewrite
other peoples code, since, gee whiz, "foo" is not quite the perfect name
for that darn variable, "bar" would be just slightly better, and on and
on. You can see why I prefer code to commentary.
...
>>
>> 1. I think that Gregg Reynolds and I agree on a lot, but I would add to
>> his remarks that there is almost always a human audience for source code,
>> as well as the compiler/interpreter. Sometimes, the audience is just the
>> originally programmer, perhaps at a later date. (If I missed something,
>> Gregg, sorry, but I don't think you disagree, anyway.)
>>
>
>I agree; whoever writes the code automatically forms an "audience" of one.
>I guess I would say "reader/responder".
Hmmm. Common Lisp is about 25 years old. Assume Clojure lives that long.
> What are the odds that the original authors will be maintaining the
> code? Will the code still be "an audience of one"? Are you sure that's
> a worthwhile goal?
>
I think you may have misunderstood me (dunno about Gary): my point is that
even one-off code that gets discarded immediately has a human reader,
namely the author. A statement of (minimal) fact, not a goal.
...
>
> Sophisticated Lisp programmers use macros A LOT.
That's because they are language designers, and they know it.
> expanding into macros expanding into macros. Quick, what does the
> spadcall macro do?
>
HCF?
>Exactly. Conclusion: it's hard, maybe impossible, to generalize about what
> >all code should look like. Maybe it's essentially pluralistic.
>
> Yes, it is hard to generalize about what all code should look like. But
> it is not hard to generalize that reading natural language explanations
> is faster, more accurate, and a lot easier than reverse-engineering
> code.
Whoa Nelly! I don't agree with that at all, either in principle or by
experience. Well, ok, you've rigged the game. Easier than
"reverse-engineering code" - what does that mean? I guess you mean reading
well-written natural language explanations is faster etc. than reading
badly written code - but so what? It's not a meaningful comparison. Would
you take a comparison between a sample of well-written code and a sample
badly written LP as evidence against LP? I would not. To me the question
is whether well-written natural language explanation adds anything of
substance to well-written code.
> It is MUCH easier to understand Greg Humphrey's rendering code
> than it is to understand the Clojure internals.
>
Ok, but I don't see how exhibiting a piece of transparent code next to a
piece of opaque code demonstrates anything.
>
> Consider a randomly chosen paragraph from Physically Based Rendering
> (p356):
>
> To do the permutation, this function loops over the samples, randomly
> permuting the sample points in one dimension at a time. Note that this
> is a different permutation than the earlier Shuffle() routine: that
> routine does one permutation, keeping all nDim sample points in each
> sample together, while here nDim separate permutations of a single
> dimension at a time are done. (Figure 7.21)
>
> for (uint32_t i = 0; i < nDim; ++1) {
> for (uint32_t j = 0; j < nSamples; ++j) {
> uint32_t other = j + (rng.RandomUInt() % (nSamples - j));
> swap(samples[nDim + j + i], samples[nDim * other + i]);
> }
> }
>
> Footnote: While it's not necessary to permute the first dimension of
> the LHS pattern, the implementation here does so anyway since making
> the elements of the first dimension be randomly ordered means that LHS
> patterns can be used in conjunction with sampling patterns from other
> sources without danger of correlation between their sample points.
>
> So we learned what the code does. We also learned not to "optimize the
> code" by replacing it with Shuffle(). Further, we learned that we
> shouldn't "optimize the code" by removing the apparently useless
> shuffle of the first dimension. And, as a bonus, we get a figure.
> NONE OF THIS INFORMATION IS IN THE CODE ITSELF.
>
For "what the code does":
/* inline random, total, in-place matrix permutation - contrast Shuffle() */
...code...
The first line of commentary is totally redundant, so it is a waste of time
to read both it and the code. As for what not to "optimize": if none of
the conclusions you draw are in the code, they're not in the commentary,
either. Replacing the code with Shuffle would change the meaning from
total to partial permutation, so it would not be an optimization. Ditto
for replacing it with Shuffle. But the explanation of the difference
between this code and Shuffle is unhelpful to me - what does "[the Shuffle]
routine does one permutation, keeping all nDim sample points in each sample
together" mean? I'd have to read that code to find out, so the commentary
has just wasted my time. As for the permutation of the first dimension,
here the commentary is bad again - first it says it is not necessary, then
it explains that it is necessary if you want to use it for a specific
purpose. As for the figure, I assume the book has some kind of graphic. I
don't think I need a graphic to understand the code - it's a simple
permutation.
So for me at least, this example counts against rather than for the point
that (I assume) you want to make. The point I will make is not that
documentation is inherently evil - far from it - but merely that
explanatory prose is not a *necesssary* condition of readable code. And it
often makes things worse, as in this case.
>
> In addition, this code lives in an organizing structure. It is
> in Chapter 7: Sampling and Reconstruction
> Section 7.3: Stratified Samples
>
>
> Heck, it is only 4 lines of C++. Why bother? *I* can read C++. I can
> even reverse engineer it (probably by inventing the diagram in Figure
> 2.7 on a napkin). Maybe it lives in the src/SamRecon/StratSam, which is
> all the organization necessary. :-) But I can't reverse engineer the
> important information in either paragraph of text.
>
> For comparison, refer back to the multi-page Java code I posted
> from the Clojure core. As a maintenance programmer, which would you
> rather maintain?
>
Really? What's the point of comparing 4 lines of C++ and multiple pages of
Java? I can tell you I would rather maintain the four lines of C++ without
the largely useless commentary. I would also rather maintain a
(well-written) plain Pascal version of "Printing the primes" than the LP
version Knuth uses in his paper on LP (a web search will turn up a preprint
copy).
... snip ...
Languages come into fashion all the time. Almost all of them disappear.
> Axiom and Clojure are worthwhile efforts. We really need a mindset that
> extends into the future, communicating with the maintainers.
>
Dunno anything about Axiom, I'm afraid. As for the future, I think it is
best served by doing our best to write clear *code* now. You mentioned
Axiom has a 30 year timeline. I won't be surprised if humans do relatively
little hands-on coding (or code reading) by then. Between AI and automated
reasoning (for which the commentary part of LP is irrelevant) I expect the
number of programmer jobs to shrink drastically by then.
In any case, I wish you luck with your Clojure internals project. If XML
doesn't give you the hives check out
https://github.com/mobileink/xsl.clj-ext - I think it could be used to good
effect to document the APIs, if not the internals, by example.
-Gregg
--
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
---
You received this message because you are subscribed to the Google Groups
"Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
