Hi, I am an admirer of LISP... I only wish I knew it better. That being
said,
I would like (and dare) to suggest an improvement - introducing an idea
we
use in Physics. When an equation is too long, separate sets of
parentheses
are used in order to make the "sentence" more readable. The suggestion
is
to include these different sets as an integral part of the LISP
interpreter with
a standardized (customizable?) "hierarchy"
The Parentheses "Hierarchy": < { [ ( ) ] } >
I submit a sample comparison test below:
(cond ( ( = 0 (mod n i) ) ( + i sum ) ) )
<cond { [ = 0 (mod n i) ] [ + i sum ] } >
The "if-then" clauses are immediately recognizable. Whereas
the "LISPy" statement leaves me scanning the line several
times, and then having to check it again.
I have been told how to do this using "set-macro-char," but this
is an advanced feature which I can only imitate:
(set-macro-character #\[ #'(lambda (stream char)
(read-delimited-list #\] stream)))
(set-macro-character #\] (get-macro-character #\)))
My point is to set this up in the "kernel" and enable everyone,
especially struggling students (like myself), to easily read LISP.
In fact, the above definition may make the case for me. :)
Thanks for reading this note.
--
joe comunale
Queens College, NY
joe comunale <·····@qcunix.qc.edu> writes:
>(cond (( = 0 (mod n i)) (+ i sum)))
[snip]
> The "if-then" clauses are immediately recognizable. Whereas
> the "LISPy" statement leaves me scanning the line several
> times, and then having to check it again.
(cond ((= 0 (mod n i))
(+ i sum)))
Why not take advantage of your editor's ability to format
your code? (Parens matching, indenting etc.)
--
Lars
joe comunale <·····@qcunix.qc.edu> writes:
> Hi, I am an admirer of LISP... I only wish I knew it better. That
> being said, I would like (and dare) to suggest an improvement -
> introducing an idea we use in Physics. When an equation is too
Similar schemes exist in mathematics, too (though one traditionally
changes the size/boldness of parentheses, rather than their
appearance). And since computer scientists are normally well
acquainted with mathematics, it stands to reason, that people before
you had similar ideas. Since we still use only one form of
parentheses, this might be an indication that your idea doesn't work
out very well in practice... I'd also suggest you head over to
www.deja.com, and take a look at the recent discussion in this group
on indentation style: Many of the same arguments will apply...
> long, separate sets of parentheses are used in order to make the
> "sentence" more readable. The suggestion is to include these
> different sets as an integral part of the LISP interpreter with a
> standardized (customizable?) "hierarchy"
>
> The Parentheses "Hierarchy": < { [ ( ) ] } >
>
> I submit a sample comparison test below:
>
> (cond ( ( = 0 (mod n i) ) ( + i sum ) ) )
>
> <cond { [ = 0 (mod n i) ] [ + i sum ] } >
>
> The "if-then" clauses are immediately recognizable. Whereas
> the "LISPy" statement leaves me scanning the line several
> times, and then having to check it again.
Both lines are not very well readable, but the second line is *worse*
(and although this is only my humble opinion, I'm pretty sure that >90%
of the readers of comp.lang.lisp will concur). A readable version
would go something like this:
(cond
((= 0 (mod n i))
(+ i sum))
...)
Since no one would write a cond with only one clause (which doesn't
even side-effect anything), this would probably be rewritten like
this:
(when (= 0 (mod n i))
(+ i sum))
Or to make the value of the form in the else case more explicit:
(if (= 0 (mod n i))
(+ i sum)
nil)
Or even:
(if (zerop (mod n i))
(+ i sum)
nil)
See the above mentioned thread on indentation of why this is more
readable to others, and will be more readable to you, once you've
gotten used to this indentation style.
> My point is to set this up in the "kernel" and enable everyone,
> especially struggling students (like myself), to easily read LISP.
> In fact, the above definition may make the case for me. :)
This is a very bad idea, for the usual reasons. People don't make C
more readable by replacing { and } with BEGIN and END, anymore than
introducing a divergent syntax for Lisp will make it more readable:
Not only will this make the code written by the students like yourself
unreadable to any other Lisp programmer (and keep 100% of the Lisp
code out there unreadable to you), but I also seriously doubt that any
student, who has trouble reading good Lisp code written using the
canonical, well-documented Lisp style, will have less trouble using a
variant syntax, that is documented _nowhere_ and understood and used
by _noone_ else.
Just like in 99.9999% percent of all cases, the ground-breaking
"improvements" on mathematical notation or definitions by students are
bad ideas in the end, so it is usually the case with "improvements" to
programming languages by people just learning them. Usually, you
first study the field you enter, to make sure you understand the
ramifications of your improvements (and when they still sound good
after you have done them, _then_ you _might_ be onto something).
So I'd advise you to get hold of a good book on Lisp, like Graham's
"ANSI Common Lisp", or Norvig's "Paradigms of AI Programming", or any
other recent books on Lisp, and read the sections where they explain
indentation style and reading/writing of Lisp code. Then go, and
exercise reading of existing Lisp code (this has other benefits, too,
and learning to read code is at least as important as learning to
write good code. Programming and literature are quite alike in this
respect). And you will soon see, that we don't write Lisp like we do,
just to make life for students harder (to the contrary).
> Thanks for reading this note.
Thanks for taking this advice seriously ;)
Regs, Pierre.
--
Pierre Mai <····@acm.org> PGP and GPG keys at your nearest Keyserver
"One smaller motivation which, in part, stems from altruism is Microsoft-
bashing." [Microsoft memo, see http://www.opensource.org/halloween1.html]
Pierre R. Mai wrote:
[someone proposing different kinds of parens in Lisp wrote:]
>> (cond ( ( = 0 (mod n i) ) ( + i sum ) ) )
>>
>> <cond { [ = 0 (mod n i) ] [ + i sum ] } >
.
> Both lines are not very well readable, but the second line is *worse*
> (and although this is only my humble opinion, I'm pretty sure that >90%
> of the readers of comp.lang.lisp will concur).
I concur. And I'm a mathematician, and therefore used to having
lots of different kinds of grouping symbols. I think the idea of
having more than one way of writing grouping *can* be helpful,
but not when it's used as promiscuously as this.
Incidentally, although the Right Way to write the above code
involves indenting it, it can be made (to my eyes) much more
readable simply by removing some gratuitous whitespace:
(cond ((= 0 (mod n i)) (+ i sum)))
But it's *much* more readable written on two lines and sensibly
indented.
Some implementations of Scheme let you use two kinds of paren,
and require them to be matched. With that convention you might
write the above as
(cond [(= 0 (mod n i)) (+ i sum)])
which is possibly a little more readable than either of the
other versions. But there are probably better things to do
with a pair of matching delimiters than this, in these days
of auto-indenting syntax-colouring bracket-matching editors.
(I don't mean that the *language* should give them a meaning,
but they should be free for use by individual users who want
them for vectors or hashtables or infix expressions or embedded
Prolog or whatever.)
--
Gareth McCaughan ················@pobox.com
sig under construction
joe comunale <·····@qcunix.qc.edu> writes:
> The Parentheses "Hierarchy": < { [ ( ) ] } >
>
> I submit a sample comparison test below:
>
> (cond ( ( = 0 (mod n i) ) ( + i sum ) ) )
>
> <cond { [ = 0 (mod n i) ] [ + i sum ] } >
>
> The "if-then" clauses are immediately recognizable. Whereas
> the "LISPy" statement leaves me scanning the line several
> times, and then having to check it again.
The mixed parentheses style is not more legible to me. It may resync
better, which is good, but having to manage multiple types of
parenthesis seems too big a cost. It also grabs too many characters,
including greater-than / less-than. I prefer introducing a specific
resync string, but most on this group hate the idea.
FWIW, Lisp programmers generally don't count parenthesis. The only
time I ever do is when I'm reading something outside of emacs, and
then if it's more than a line or so, I just fetch it into emacs. One
could almost say that Lisp is an indentation-syntax language (eg,
Perl), and the parenthesis are just to keep the machine from getting
lost, eg if one accidentally reformats code.
Which brings me to another topic, for which I expect to be roundly
flamed. The comment syntax in Lisp is suboptimal. It doesn't survive
reformatting -- even emacs can screw up comment-vs-code when you
reformat (ie, when you fill-paragraph). It also can't be handled well
in code transformations. Any sort of automatic code transformer loses
all the comments unless it makes an extraodrinary effort to read them
and track where they came from. What I'd like to see is comments be
of a piece with code, and be winnowed out by another stage in the
read-eval loop (read-compile loop, or whatever's being done). Now
everybody flame me for saying it.
--
Tom Breton, http://world.std.com/~tob
Ugh-free Spelling (no "gh") http://world.std.com/~tob/ugh-free.html
Tom Breton <···@world.std.com> writes:
> Which brings me to another topic, for which I expect to be roundly
> flamed. The comment syntax in Lisp is suboptimal. It doesn't survive
> reformatting -- even emacs can screw up comment-vs-code when you
> reformat (ie, when you fill-paragraph).
`fill-paragraph' works ok on code that contains embedded comments.
How does emacs screw it up?
> It also can't be handled well
> in code transformations. Any sort of automatic code transformer loses
> all the comments unless it makes an extraodrinary effort to read them
> and track where they came from. What I'd like to see is comments be
> of a piece with code, and be winnowed out by another stage in the
> read-eval loop (read-compile loop, or whatever's being done).
[...]
I agree, though the current syntax doesn't have to change. ';' could
be made into a macro character that would cause
(progn
;; hack follows
(+ 2 2))
to be read as
(progn
(comment "hack follows")
(+ 2 2))
.
There are probably better ways to do it though.
The benefit, as I see it, of "READable" comments is that it would
enable a programmer to work without files of source code. Comments
are the only information (other than whitespace) lost upon READing.
If comments were READable, than evaluating a bunch of definitions
would be as good as saving them into a file.
Some forms would have to be altered to support such an environment.
DEFUN would have to save the uncompiled function definition somewhere
(on the plist, for example) to prevent it from being overwritten upon
compilation.
Such a lisp system really seems appealing. To edit a function in such
a system you would check it out (function definition printed from lisp
memory to editor buffer), modify it, and check it back in again
(evaluate it). Or you could check an entire package out. The system
could also handle version control on its own. A dumped image could be
considered a version control snapshot.
How would the following be handled?
(setq residents-of-McWorld
'(RonaldMcDonald ;; is the head honcho.
Grimace ;; is purple.
Birdie ;; loves to fly.
))
Or is this enough proof that the idea is flawed?
--
Samir Barjoud
·····@mindspring.com
* Samir Barjoud wrote:
> I agree, though the current syntax doesn't have to change. ';' could
> be made into a macro character that would cause
> (progn
> ;; hack follows
> (+ 2 2))
> to be read as
> (progn
> (comment "hack follows")
> (+ 2 2))
> .
This is pretty much exactly how the Xerox lisp machines did it.
Interlisp had (I think) a comment syntax that was something like (*
comment text), and the CL layer on top of it arranged to read CL-style
comments like this. Like most things on the D-machines it worked well
most of the time but occasionally ate you alive. I once did a thing
for CL that read comments as structures: the most annoying thing is
that XP isn't up to printing comments `right' once you've read them,
or at least I couldn't make it do it about 8 years ago. You also get
the problem I describe below.
> Such a lisp system really seems appealing. To edit a function in such
> a system you would check it out (function definition printed from lisp
> memory to editor buffer), modify it, and check it back in again
> (evaluate it).
In fact you'd just edit the structure in core, probably with an editor
called SEdit (or DEdit if you were older).
> (setq residents-of-McWorld
> '(RonaldMcDonald ;; is the head honcho.
> Grimace ;; is purple.
> Birdie ;; loves to fly.
> ))
I think you just do a walk removing the comment objects before you
evaluate. A much more interesting problem is something like this:
#(1 ; ehem
2 3)
which would mean you'd have to read #(...) as something that would get
turned into an array later on, by the thing that stripped the comments
I guess. I don't know how the dmachines dealt with this.
It's really a shame how much information has been lost about the
D-machines: the situation with the MIT-derived systems is bad enough,
but there are some still extant, and some people still enthuse about
them, but I don't know of anyone who has a working Xerox machine, and
you never see anyone raving about them. Perhaps that's because they
weren't as good at the MIT systems -- they weren't I think, but they
were still pretty interesting, and their window system, for instance,
was a lot more mainstream than the Symbolics one (not surprisingly
since it came from Xerox).
The strangest thing is that I (day?)dream about mine having a colour
screen, when it never did have (if they ever did at all).
--tim
From: William Deakin
Subject: Re: Comments, was Re: Parentheses Hierarchy
Date:
Message-ID: <3795A9B2.4A8490DB@pindar.com>
Tim Bradshaw wrote:
> The strangest thing is that I (day?)dream about mine having a colour
> screen, when it never did have (if they ever did at all).
I work (print) in black and yellow and remember many happy days of coding on
a QUME vt100... Hmmm. Who needs that colour rubbish anyway.
:-) will
In article <·················@mindspring.com>,
Samir Barjoud <·····@mindspring.com> writes:
> I agree, though the current syntax doesn't have to change. ';' could
> be made into a macro character that would cause
>
> (progn
> ;; hack follows
> (+ 2 2))
>
> to be read as
>
> (progn
> (comment "hack follows")
> (+ 2 2))
> .
Would you really want
(if (eq a b)
; I really want this to be done when a == b
(do-something))
to turn into
(if (eq a b)
(comment "I really want this to be done when a == b")
(do-something))
Lots of forms would have to become "comment aware" to keep everything
working. Writing a new macro, for instance, would become a lot more
complicated. Heck, most of us don't handle doc strings in our macros as it is.
Mike McDonald
·······@mikemac.com
·······@mikemac.com (Mike McDonald) writes:
> In article <·················@mindspring.com>,
> Samir Barjoud <·····@mindspring.com> writes:
>
> Would you really want
>
> (if (eq a b)
> ; I really want this to be done when a == b
> (do-something))
>
> to turn into
>
> (if (eq a b)
> (comment "I really want this to be done when a == b")
> (do-something))
>
> Lots of forms would have to become "comment aware" to keep everything
> working. Writing a new macro, for instance, would become a lot more
> complicated.
That's why it should be a separate stage IMO. First you read the
code. Now you've got a few extra sexps, but since you haven't done
anything with them, they can't cause problem yet.
If you are eval'ing, compiling, or using it as a parm to a macro, the
comments would be winnowed first. IMO, macros should be winnowed both
before and after, because both they and their parms may have comments.
Now there are no extra sexps, so they still can't cause problems.
If you wanted to walk the code yourself, you could either just call
the winnowing function if you didn't care about comments, or deal with
them yourself in whatever fashion you like.
I suggest that there'd be another type of macro, distinguished only by
not passing its input thru the winnowing stage first, used to assist
comment-preserving code transformations.
--
Tom Breton, http://world.std.com/~tob
Ugh-free Spelling (no "gh") http://world.std.com/~tob/ugh-free.html
Tom Breton <···@world.std.com> writes:
> ·······@mikemac.com (Mike McDonald) writes:
>
> > In article <·················@mindspring.com>,
> > Samir Barjoud <·····@mindspring.com> writes:
> >
>
> > Would you really want
> >
> > (if (eq a b)
> > ; I really want this to be done when a == b
> > (do-something))
> >
> > to turn into
> >
> > (if (eq a b)
> > (comment "I really want this to be done when a == b")
> > (do-something))
> >
> > Lots of forms would have to become "comment aware" to keep everything
> > working. Writing a new macro, for instance, would become a lot more
> > complicated.
>
> That's why it should be a separate stage IMO. First you read the
> code. Now you've got a few extra sexps, but since you haven't done
> anything with them, they can't cause problem yet.
This really doesn't work. COMMENT used to be a form in Maclisp.
(COMMENT "This is a test.")
or
(COMMENT THIS IS A TEST/.) ;Maclisp used / instead of \
People experimented with having ";" expand to COMMENT but it's a mess.
It doesn't work in literals and there is no way to get it to work.
Even in forms, it creates a problem with return values. The COMMENT
form returned the symbol COMMENT. Consider:
(defun foo () (comment This does nothing.))
This returned COMMENT in interpreted code. I can't remember if the
compiled code returned COMMENT or NIL or what. But it was kind of a mess
either way, if you ask me. You can, of course, always create this yourself.
But you're repeating a lot of history to no good end I can imagine.
If you are concerned with the very specialized task of writing a code
editor that reads and writes code exactly as the user wrote it, probably
text is a better representation than s-expressions since the user will
want it exactly as s/he wrote it. If you're not doing that, it's not
clear that anything is needed other than the code to execute. That's
how we got to where we are today.
I mostly think this is a non-issue and that
life is full of bigger problems than this.
In some sense, the creation of Common Lisp was about putting to rest
myriad doofy little issues like this that we'd wasted years debating and
saying "it's more important that there is an answer than that the answer
is what any one person likes best". It's still ok for a user to privately
deviate, but I think it's a bad idea to get anyone else into the debate.
If you have a personal preference, just implement it. Don't make anyone else
have to agree, because people won't and because there is no point to getting
them to.
> I suggest that there'd be another type of macro, distinguished only by
> not passing its input thru the winnowing stage first, used to assist
> comment-preserving code transformations.
I think you'd have trouble making this work. It would mean rewriting all
existing macros to accomodate. You cannot keep up... unless you're
banking on the lisp industry to stagnate enough that it will operate
at a standstill while you try. It's just not worth it. (JMO)
But if you want to try, the way to do it, as it has always been is not
to assert that this is needed, but to fully implement it and then show
people and say "didn't this work well?" The proof has always been in
the doing.
Kent M Pitman <······@world.std.com> writes:
> Tom Breton <···@world.std.com> writes:
>
> > ·······@mikemac.com (Mike McDonald) writes:
> >
> > >
> > > Lots of forms would have to become "comment aware" to keep everything
> > > working. Writing a new macro, for instance, would become a lot more
> > > complicated.
> >
> > That's why it should be a separate stage IMO. First you read the
> > code. Now you've got a few extra sexps, but since you haven't done
> > anything with them, they can't cause problem yet.
>
> This really doesn't work. COMMENT used to be a form in Maclisp.
> (COMMENT "This is a test.")
> or
> (COMMENT THIS IS A TEST/.) ;Maclisp used / instead of \
I don't see where this has any bearing on that. Note that the
un-winnowed representation isn't even eval'ed.
> People experimented with having ";" expand to COMMENT but it's a mess.
> It doesn't work in literals and there is no way to get it to work.
I don't know how maclisp did it, but I see no problem escaping a
string.
> Even in forms, it creates a problem with return values.
Which is why comments should be stripped out before evaluating.
> If you are concerned with the very specialized task of writing a code
> editor that reads and writes code exactly as the user wrote it, probably
> text is a better representation than s-expressions since the user will
> want it exactly as s/he wrote it. If you're not doing that, it's not
> clear that anything is needed other than the code to execute. That's
> how we got to where we are today.
There's a whole world of possibilities of code transformation in
between there.
>
> > I suggest that there'd be another type of macro, distinguished only by
> > not passing its input thru the winnowing stage first, used to assist
> > comment-preserving code transformations.
>
> I think you'd have trouble making this work. It would mean rewriting all
> existing macros to accomodate.
How so? ISTM it affects zero existing macros. It would require
evaluating macros differently, but that's one shot per Lisp
environment.
> But if you want to try, the way to do it, as it has always been is not
> to assert that this is needed, but to fully implement it and then show
> people and say "didn't this work well?" The proof has always been in
> the doing.
I've done that with other projects, and it's not as rewarding as it
sounds.
--
Tom Breton, http://world.std.com/~tob
Ugh-free Spelling (no "gh") http://world.std.com/~tob/ugh-free.html
In article <··············@world.std.com>,
Tom Breton <···@world.std.com> wrote:
>Kent M Pitman <······@world.std.com> writes:
>> Even in forms, it creates a problem with return values.
>
>Which is why comments should be stripped out before evaluating.
Are you saying they should be stripped out before expanding macros? The
problem with that is that the stripper can't tell at that time whether
(comment ...) is in a place that will be evaluated or if it's supposed to
be constant data. For instance, I can write:
(defmacro my-quote (thing)
`(quote ,thing))
Now, (my-quote (comment a b c)) had better evaluate to (COMMENT A B C); the
"comment" should not be removed before expanding the macro.
But if you wait until after macro expansion, many macros will have to be
comment-aware. Consider:
(defmacro my-prog1 (first-form &body rest-forms)
`(let ((return-val ,first-form))
,@rest-forms
return-val))
What happens to:
(my-prog1
(comment This is a comment)
3
(print "foo"))
This will expand into
(let ((return-value (comment This is a comment)))
3
(print "foo")
return-value)
which is clearly not what was intended.
--
Barry Margolin, ······@bbnplanet.com
GTE Internetworking, Powered by BBN, Burlington, MA
*** DON'T SEND TECHNICAL QUESTIONS DIRECTLY TO ME, post them to newsgroups.
Please DON'T copy followups to me -- I'll assume it wasn't posted to the group.
Barry Margolin <······@bbnplanet.com> writes:
> In article <··············@world.std.com>,
> Tom Breton <···@world.std.com> wrote:
> >Kent M Pitman <······@world.std.com> writes:
> >> Even in forms, it creates a problem with return values.
> >
> >Which is why comments should be stripped out before evaluating.
>
> Are you saying they should be stripped out before expanding macros? The
> problem with that is that the stripper can't tell at that time whether
> (comment ...) is in a place that will be evaluated or if it's supposed to
> be constant data. For instance, I can write:
>
> (defmacro my-quote (thing)
> `(quote ,thing))
>
> Now, (my-quote (comment a b c)) had better evaluate to (COMMENT A B C); the
> "comment" should not be removed before expanding the macro.
Here's where we disagree. You wouldn't expect...
(my-quote ;;a b c
)
to place ;;a b c in the output. Indeed, to do so wouldn't even be
meaningful. You wouldn't expect these comments to behave differently.
You hint another point which is valid: (comment ... ) may not be the
best syntax (FWIW, it wasn't my suggestion). :comment "a b c" or
&comment "a b c" may be more intuitive.
--
Tom Breton, http://world.std.com/~tob
Ugh-free Spelling (no "gh") http://world.std.com/~tob/ugh-free.html
Tom Breton <···@world.std.com> writes:
> > > I suggest that there'd be another type of macro, distinguished only by
> > > not passing its input thru the winnowing stage first, used to assist
> > > comment-preserving code transformations.
> >
> > I think you'd have trouble making this work. It would mean rewriting all
> > existing macros to accomodate.
>
> How so? ISTM it affects zero existing macros. It would require
> evaluating macros differently, but that's one shot per Lisp
> environment.
If you make ;foo be a "form", then either you cannot put a comment
in situations like (let ((x y) ;foo
(z w))
...)
or else your macro has to be adjusted to expect "comments" to appear where
they are not presently expected. Expanding this to
(let ((x y) (comment "foo") (z w)) ...)
will not do. That's what I had understood you to be saying you wanted to do.
> > But if you want to try, the way to do it, as it has always been is not
> > to assert that this is needed, but to fully implement it and then show
> > people and say "didn't this work well?" The proof has always been in
> > the doing.
>
> I've done that with other projects, and it's not as rewarding as it
> sounds.
Perhaps I was too subtle. I was expecting you would think it was not
rewarding and in such conditional world where you agreed with me on this
point, my suggestion to you was going to be that you don't do the thing
then. That is, that you just live with what we have now and find a project
that matters instead of one that has both been fought already and that
really doesn't matter (IMO). If, on the other hand, you feel it's what
you'd like on your gravestone ("He made it possible to read and
manipulate not just code but the comments that wend their way among them"),
then by all means, go after it. But life is short, and I recommend you
do something that matters more.
Kent M Pitman <······@world.std.com> writes:
> Tom Breton <···@world.std.com> writes:
>
>
> If you make ;foo be a "form", then either you cannot put a comment
> in situations like (let ((x y) ;foo
> (z w))
> ...)
> or else your macro has to be adjusted to expect "comments" to appear where
> they are not presently expected.
I'm going to have to explain the winnowing stage again, or rather the
read-winnow-eval loop.
State one: The code is sitting there being ASCII.
Stage one: Read it.
State two: The code is lists, vectors, etc, including comments.
Stage two: Winnow it.
State three: The code is lists, vectors, etc, without
comments. Exactly the same as you get now.
Stage three: Eval it. Or compile it, or call a macro and eval the
result, etc. Anything along the lines of "now do what the code says"
goes here.
For code transformations, it would go:
State one: The code is sitting there being ASCII.
Stage one: Read it.
State two: The code is lists, vectors, etc, including comments.
Stage two: Transform it, managing the comments as appropriate to your
transformation.
State three: The code is some other arrangement of lists, vectors,
etc, including comments.
State three: Write it back out.
State four: The code is sitting there being ASCII, transformed in some
useful way. Comments have not been lost.
> > > But if you want to try, the way to do it, as it has always been is not
> > > to assert that this is needed, but to fully implement it and then show
> > > people and say "didn't this work well?" The proof has always been in
> > > the doing.
> >
> > I've done that with other projects, and it's not as rewarding as it
> > sounds.
>
> Perhaps I was too subtle. I was expecting you would think it was not
> rewarding and in such conditional world where you agreed with me on this
> point, my suggestion to you was going to be that you don't do the thing
> then. That is, that you just live with what we have now and find a project
> that matters instead of one that has both been fought already and that
> really doesn't matter (IMO). If, on the other hand, you feel it's what
> you'd like on your gravestone ("He made it possible to read and
> manipulate not just code but the comments that wend their way among them"),
> then by all means, go after it. But life is short, and I recommend you
> do something that matters more.
Well, I thank you for taking such care about my time and energy.
Really. That's very sweet.
I'm sitting on the fence wrt actually doing it. It would make a few
things I'd like to do easier, but as you point out, it probably won't
be rewarding beyond that.
--
Tom Breton, http://world.std.com/~tob
Ugh-free Spelling (no "gh") http://world.std.com/~tob/ugh-free.html
Tom Breton <···@world.std.com> writes:
> State two: The code is lists, vectors, etc, including comments.
> Stage two: Winnow it.
>
> State three: The code is lists, vectors, etc, without
> comments. Exactly the same as you get now.
No, not exactly the same as you get now. Right now, *any* object can be
quoted. QUOTE's arguments are an inviolate space that nothing enters.
You seek to change it to say that it's safe for certain operations (the
comment-removing ones) to enter without knowledge of what is safe or
desirable to remove and what is not. This is not what I consider reasonable.
It's like giving the web police to search your web pages and remove anything
that looks like bad words, without regard to the fact that somewhere there
might be a page of the words that are to be removed, or pages of case law
about whether certain words are ok, only to find that the program that
"winnowed" these pages removed the offensive words, in spite of quotation
and/or other specialized context.
It's further complicated by the fact that you can't look for (QUOTE x)
becuase of situations like
(case x ((quote defun) "delay a while") ((+ - *) "more aggressive"))
where (quote defun) is not a quoted form.
And it's further complicated by the fact that even ordinary code might
be "constructed" and not passed through the reader, so all macros everywhere
would have to know whether it was "constructed for printing" (that is,
contains helpful comments that might need removing) or "constructed for
execution" (that is, has comments in awkward places removed and is safe for
execution).
And it's further complicated by the fact that the "macro expansion" phase
is itself opaque to quoting so that
(macrolet ((foo (x) `',x))
(foo (x ;this is a test
y)))
quotes x but you won't know it quotes x until you macroexpand it. But being
a macroexpander, you're suggesting that the comments would be removed before
the macro gets to see the arguments. (The halting problem gets involved here
if you want to solve this by code-analysis before actually running the macro.)
And it's further complicated by the fact that macros can expand into other
calls that might or might not be macros. for example,
(macrolet ((foo (x) (bar x)) (bar (x) `',x))
(foo x))
Here it's clear that (foo x) must not only be entered but able to wholly
complete its action in order to find out whether the item in question
is quoted becuase it's BAR, not FOO, that decides it is quoted.
And it's further complicated by the fact that macros simultaneously think
of some forms as quoted and not by dual use of the self-same datum. Consider
(macrolet ((foo (x) `(if x ',x)))
(foo (car ;this is like first
'(t nil t t))))
where this expands to
(if (car ;this is like first
'(t nil t t))
'(car ;this is like first
'(t nil t t)))
where *if* ";this is like first" is a form, then I want it to be quoted by
the quote, but at the same time, I want it NOT to be a form in the IF.
So there is a problem of overconstrained situation.
In short, EITHER it's the case that macros would have to expect quoted
objects all over the place OR it's the case that you would break quotation
making it impossible for the language to be properly reflective. Right
now, QUOTE is capable of quoting anything that comes out of READ. You
would be punching a big hole in that, and crippling the language's ability
to reason about its own data.
Kent M Pitman <······@world.std.com> writes:
> Tom Breton <···@world.std.com> writes:
>
> > State two: The code is lists, vectors, etc, including comments.
> > Stage two: Winnow it.
> >
> > State three: The code is lists, vectors, etc, without
> > comments. Exactly the same as you get now.
>
> No, not exactly the same as you get now. Right now, *any* object can be
> quoted. QUOTE's arguments are an inviolate space that nothing enters.
> You seek to change it
No, in the status quo, comments already are removed from quotes.
(quote ;;A
;;B
C
;;D
E)
=> (quote C E)
So it is exactly the same as what you get now.
Also, quote is not generally inviolate:
(defun invade-quote ( &rest l)
(if
(eq (car l) 'quote )
(do-stuff-to (cdr l))
l))
(invade-quote 'quote "a" )
or if you prefer,
(defun invade-quote-1 (a)
(if
(eq (car a) 'quote )
(do-stuff-to (cdr a))
a))
(invade-quote-1 '( quote "a") )
> It's like giving the web police to search your web pages and remove anything
> that looks like bad words,
You know that I'm not going to grant that analogy.
> It's further complicated by the fact that you can't look for (QUOTE x)
> becuase of situations like
> (case x ((quote defun) "delay a while") ((+ - *) "more aggressive"))
> where (quote defun) is not a quoted form.
Again, quote is not special in this respect. No need to go looking
for 'quote.
> And it's further complicated by the fact that even ordinary code might
> be "constructed" and not passed through the reader,
Which doesn't matter. I don't mean to be snippy, but that should have
been clear from last time. The reader only does what it already does.
> so all macros everywhere
> would have to know whether it was "constructed for printing" (that is,
> contains helpful comments that might need removing) or "constructed for
> execution" (that is, has comments in awkward places removed and is safe for
> execution).
Not correct. Again, winnowing would be a new stage. I don't know how
I can make it clearer.
> And it's further complicated by the fact that the "macro expansion" phase
> is itself opaque to quoting
Again with the quoting. quote is not special wrt comments, and still
wouldn't be.
[Two more variations on quoting snipped]
> making it impossible for the language to be properly reflective. Right
> now, QUOTE is capable of quoting anything that comes out of READ.
Finally an argument about why you would even want quote to do that. I
feel compelled to point out that aside from this final paragraph, your
post addressed your own idea, not mine.
However, I don't think that argument works. Already quote is not
capable of quoting comments, regardless that read looks at them.
If the fact that there is a stage where comments can be in all sorts
of places, including inside quote, disturbs you, just think of the
post-winnowing stage as being the one you want to work with.
> You
> would be punching a big hole in that, and crippling the language's ability
> to reason about its own data.
Again, after winnowing you have exactly what you have now.
And comments aren't going to be mechanically reasoned about anyways,
and aren't now, so where do you see a problem?
--
Tom Breton, http://world.std.com/~tob
Ugh-free Spelling (no "gh") http://world.std.com/~tob/ugh-free.html
On Sat, 24 Jul 1999 20:22:51 GMT, Tom Breton <···@world.std.com>
wrote:
>> making it impossible for the language to be properly reflective. Right
>> now, QUOTE is capable of quoting anything that comes out of READ.
> Already quote is not
> capable of quoting comments, regardless that read looks at them.
That is not the problem. If I understand you correctly, your proposal
includes two steps:
1: transform everything of the form
; somehting
into
(comment something)
2: remove everything of the form
(comment something)
from the data.
But that means that you can never include external representations of
lists beginning with the symbol 'comment in your code. A simple
example (in Scheme):
(define comment ;comments from the program.
(lambda (message)
(display "Comment: ") (display message) (newline)))
(comment "Doing something now") ;never even seen by eval.
While this might be undesirable, it is not different in principle from
what we already have:
(define quote ;quote Shakespeare
(lambda ()
(display "To be or not to be / that is the question")))
; doesn't work either.
When combined with literals, however, this new form becomes very
confusing. While both
(append '(quote foo bar) lis) and
(append '(function foo bar) lis) works as expected,
(append '(comment foo bar) lis) is tranformed into
(append lis) before eval even sees it!
I think this is a serious weakness with the proposal.
I suppose this could be solved be by making
; something
expand into a list whose first element is not a symbol, but a special
object without an external representation, although that would break
the symmetry with quote and function .
This concern aside, I have another doubt regarding all this. How is
this new stage, when the code is read in, but the comments not yet
sifted, to be made available to the programmer? Redefining read to
return comment-forms as well as proper code would break programs which
do not expect them. On the other hand, creating a new procedure to
return that form would be no stronger then simply adding a new
procedure (definable in terms of read-char) to the standard library,
and thus this makes a language chage seem unnessesary. Finally, giving
the programmer _no_ acces to this stage opens up the old "If a tree
falls in the woods...". =)
-Ville
·······@home.se (Vilhelm Sj�berg) writes:
> On Sat, 24 Jul 1999 20:22:51 GMT, Tom Breton <···@world.std.com>
> wrote:
>
> >> making it impossible for the language to be properly reflective. Right
> >> now, QUOTE is capable of quoting anything that comes out of READ.
> > Already quote is not
> > capable of quoting comments, regardless that read looks at them.
>
> That is not the problem. If I understand you correctly, your proposal
> includes two steps:
>
> 1: transform everything of the form
> ; somehting
> into
> (comment something)
>
> 2: remove everything of the form
> (comment something)
> from the data.
Correct, modulo the details of representation.
> But that means that you can never include external representations of
> lists beginning with the symbol 'comment in your code.
Correct. You wouldn't use the chosen symbol for general use, as you
avoid a few other special symbols.
You make a good case as to why it shouldn't be the exact symbol
"comment", which is probably used in someone's code somewhere, but
that's just a question of representation.
> While this might be undesirable, it is not different in principle from
> what we already have:
Correct.
> (define quote ;quote Shakespeare
> (lambda ()
> (display "To be or not to be / that is the question")))
> ; doesn't work either.
>
> When combined with literals, however, this new form becomes very
> confusing. While both
> (append '(quote foo bar) lis) and
> (append '(function foo bar) lis) works as expected,
> (append '(comment foo bar) lis) is tranformed into
> (append lis) before eval even sees it!
(append ;;(foo bar)
lis)
is also transformed into (append lis) before eval sees it. Is that
equally disturbing? If not, then it's just an issue of
representation.
Again, good case as to why the representation shouldn't be "(comment
...)".
> This concern aside, I have another doubt regarding all this. How is
> this new stage, when the code is read in, but the comments not yet
> sifted, to be made available to the programmer? Redefining read to
> return comment-forms as well as proper code would break programs which
> do not expect them. On the other hand, creating a new procedure to
> return that form would be no stronger then simply adding a new
> procedure (definable in terms of read-char) to the standard library,
> and thus this makes a language chage seem unnessesary. Finally, giving
> the programmer _no_ acces to this stage opens up the old "If a tree
> falls in the woods...". =)
That's a good question. ISTM one can just apply normal functional
composition and decomposition.
As you point out, you want read itself to behave as before, but you
also want to be able to read without winnowing. So IMO the roster of
functions would run something like:
;;Basic functions
read-and-dont-winnow
winnow
eval-but-dont-winnow-first ;;Basically only useful for optimization.
;;Backwards-compatible functions
read, equal to (winnow (read-and-dont-winnow ... ))
eval, equal to (eval-but-dont-winnow-first (winnow ... ))
Also, eval would have to re-winnow whenever new lexical input was
seen, which basically means when it calls a macro. Treat eval's
cousins that compile,etc the same way. That seems to be about all
that would be needed.
--
Tom Breton, http://world.std.com/~tob
Ugh-free Spelling (no "gh") http://world.std.com/~tob/ugh-free.html
Tom Breton <···@world.std.com> writes:
> You make a good case as to why it shouldn't be the exact symbol
> "comment", which is probably used in someone's code somewhere, but
> that's just a question of representation.
This is the crux. It can't be any object. QUOTE must be able to
quote all objects. Can you cite an example of any object QUOTE cannot
quote? I cannot. The idea of avoiding a forbidden object is at the
crux of this. There presently is no forbidden object.
Kent M Pitman wrote:
> Tom Breton <···@world.std.com> writes:
>
>> You make a good case as to why it shouldn't be the exact symbol
>> "comment", which is probably used in someone's code somewhere, but
>> that's just a question of representation.
>
> This is the crux. It can't be any object. QUOTE must be able to
> quote all objects. Can you cite an example of any object QUOTE cannot
> quote? I cannot. The idea of avoiding a forbidden object is at the
> crux of this. There presently is no forbidden object.
It could be an unreadable object. So you'd have a function
COMMENT-INDICATOR-SYMBOL or a corresponding (constant) variable.
It still wouldn't be possible to quote lists beginning with this
magic value (well, you could do it, but under certain circumstances
the resulting thing would vanish), which would certainly be strange,
but I don't think it's obviously unacceptable.
It's not clear to me that this would buy enough for it to be worth
doing. I think Tom ought to implement his suggestion (so far as it's
possible to do this with present CLs, which ought to be pretty far),
show an actual benefit it would produce, and invite criticism from others;
this isn't a debate that works well in the abstract because it's
all about whether certain possibly-confusing possibly-useful behaviour
would end up being more confusing or more useful.
--
Gareth McCaughan ················@pobox.com
sig under construction
Kent M Pitman <······@world.std.com> writes:
> Gareth McCaughan <················@pobox.com> writes:
>
> > Kent M Pitman wrote:
> >
> > > crux of this. There presently is no forbidden object.
> >
> > It could be an unreadable object.
>
> I understood this was the intent. But there is no unreadable object
> that is presently forbidden in QUOTE, so that is a BIG change.
>
> You may be assuming that the only thing that gets compiled is code
> that is acquired through text input.
I never assumed that. That's why winnowing is a stage.
> Some code is consed up on the
> fly, and that code is capable of being considerably more complex.
> Further, some code is not externalizable, but can still be compiled
> in-core.
Which is why I say that all the analogs of eval -- anything that
"does" the code -- should work only on winnowed code. And it's OK if
they redundantly winnow it; (winnow (winnow X)) equals (winnow X)
> This is why I asked you to cite an example of something that can't be
> in code.
Er, I think you mean me.
> I know there is no such thing right now. Suggest an object
> that there exists some way to ever programmatically detect
Aha, "some way to ever programmatically detect", by which I guess you
mean to exclude comments. But then you're in the position of
asserting comments are excluded now but mustn't be then, and I can
just answer that you're criticizing your idea, not mine.
--
Tom Breton, http://world.std.com/~tob
Ugh-free Spelling (no "gh") http://world.std.com/~tob/ugh-free.html
Gareth McCaughan <················@pobox.com> writes:
>
> It's not clear to me that this would buy enough for it to be worth
> doing. I think Tom ought to implement his suggestion (so far as it's
> possible to do this with present CLs, which ought to be pretty far),
> show an actual benefit it would produce, and invite criticism from others;
> this isn't a debate that works well in the abstract because it's
> all about whether certain possibly-confusing possibly-useful behaviour
> would end up being more confusing or more useful.
Well, I've tossed together a proof-of-concept in elisp. It's very
bare-bones, just enuff to show that it works. I'm not planning on
doing more than that, at least in the near future.
--
Tom Breton, http://world.std.com/~tob
Ugh-free Spelling (no "gh") http://world.std.com/~tob/ugh-free.html
Gareth McCaughan <················@pobox.com> writes:
> Kent M Pitman wrote:
>
> > Tom Breton <···@world.std.com> writes:
> >
> >> You make a good case as to why it shouldn't be the exact symbol
> >> "comment", which is probably used in someone's code somewhere, but
> >> that's just a question of representation.
> >
> > This is the crux. It can't be any object. QUOTE must be able to
> > quote all objects. Can you cite an example of any object QUOTE cannot
> > quote? I cannot. The idea of avoiding a forbidden object is at the
> > crux of this. There presently is no forbidden object.
>
> It could be an unreadable object.
I understood this was the intent. But there is no unreadable object
that is presently forbidden in QUOTE, so that is a BIG change.
You may be assuming that the only thing that gets compiled is code
that is acquired through text input. Some code is consed up on the
fly, and that code is capable of being considerably more complex.
Further, some code is not externalizable, but can still be compiled
in-core. If it comes in with READ, it can end up in structure, and
structure can be compiled. You can't write code that manipulates
these things if there isn't the possibility it can be in code, and
if there is that possibility, it needs not to be gratuitiously removed.
This is why I asked you to cite an example of something that can't be
in code. I know there is no such thing right now. Suggest an object
that there exists some way to ever programmatically detect and I'll show
you a way to make it end up inside a QUOTE'd expression in a way that
semantically ought not be removed.
Kent M Pitman wrote:
[I said:]
>> It could be an unreadable object.
>
> I understood this was the intent. But there is no unreadable object
> that is presently forbidden in QUOTE, so that is a BIG change.
>
> You may be assuming [SNIP]
> This is why I asked you [SNIP]
Just in case it's not clear: I'm not advocating comments-as-code;
Tom Breton is. I was just observing that there's a distinction
between "you can't do this, it'll break everything" and "you
shouldn't do this, it will make the system's semantics untidier".
I think Tom's suggestion is in the latter category, not the former.
--
Gareth McCaughan ················@pobox.com
sig under construction
From: Erik Naggum
Subject: Re: Comments, was Re: Parentheses Hierarchy
Date:
Message-ID: <3141970538201704@naggum.no>
* Gareth McCaughan <················@pobox.com>
| It could be an unreadable object.
we have #. to help us READ those.
#:Erik
--
suppose we blasted all politicians into space.
would the SETI project find even one of them?
Erik Naggum <····@naggum.no> writes:
> * Gareth McCaughan <················@pobox.com>
> | It could be an unreadable object.
>
> we have #. to help us READ those.
Well, #. is just one of many ways. I can write a readmacro that returns
any given so-called unreadable object. e.g., a readmacro @ that yields
the result of `'the-stream-i-am-reading-from, so that
(eval @) => #<the stream the @ was on>
And even if I couldn't read it with any readmacro, I can still do
(eval (list 'quote your-favorite-unreadable-object))
so that readability is irrelevant.
Whether an object is unreadable is irrelevant to whether it is possible
to use in a form to evaluate, since Lisp's semantics are not defined in
terms of what you can READ but what you can CONStruct.
Hi,
Gareth McCaughan <················@pobox.com> writes:
> It's not clear to me that this would buy enough for it to be worth
> doing. I think Tom ought to implement his suggestion (so far as it's
> possible to do this with present CLs, which ought to be pretty far),
> show an actual benefit it would produce, and invite criticism from others;
> this isn't a debate that works well in the abstract because it's
> all about whether certain possibly-confusing possibly-useful behaviour
> would end up being more confusing or more useful.
I second that. My notes about useful messages thrown out to the user
by COMPILE-FILE in another post within this thread lead me to believe
that we should discuss the requirements or interests that lead Tom to
ask for the integration of comments when reading (discuss "what"
instead of "how" to do).
To me it seems like some very specific need that can and should be
solved within its own problem domain, without throwing away the
distinction between structural objects that READ returns and EVAL or
COMPILE processes and textual representations thereof within a file.
An example domain: suppose I had some web-publishing database server.
I could not care about the contents' representation and simply save
the image with all data from time to time so as to be able to back up.
OTOH, It's nice to be able to feed the server some data in an ASCII
form (for its universality and freedom of uses and manipulation by
other tools), so I ought to devise a external format (similar to the
Lispy-SGML forms discussed in this newsgroup).
Then only I might think that it would be possible that the server
writes back the file I submitted after updating some slots. Then only
should I start wondering whether comments in this file should be
preserved by such an update operation (instead of writing "do not
edit!" as found in many configuration files): only here is when
maintaining comments (and what do your require about indentation etc.)
is useful.
I think Erik Naggum and Lars Marius Garshol <······@ifi.uio.no>
expressed similar ideas in this thread.
So the need to preserve comments when reading seems to me very
specific to some application. Solutions exist for that that don't
require one to rethink the complete concepts of READ and EVAL/COMPILE.
Just my $0.02,
Jorg Hohle
Telekom Research Center -- SW-Reliability
Kent M Pitman <······@world.std.com> writes:
> Tom Breton <···@world.std.com> writes:
>
> > You make a good case as to why it shouldn't be the exact symbol
> > "comment", which is probably used in someone's code somewhere, but
> > that's just a question of representation.
>
> This is the crux. It can't be any object. QUOTE must be able to
> quote all objects. Can you cite an example of any object QUOTE cannot
> quote? I cannot. The idea of avoiding a forbidden object is at the
> crux of this. There presently is no forbidden object.
I'm first going to clarify: By "cannot be quoted", we mean that it
cannot be passed thru eval unchanged simply by using quote. Note that
this conceals a problem with your argument: It isn't clear whether the
eval function referenced winnows or not. One can simply interpret
eval as mapping to eval-but-dont-winnow.
;;(This object)
cannot presently be quoted. If you don't want to consider comments
objects, then there still wouldn't be a forbidden object.
If, OT3H, you want to call comments not objects now, but objects then,
why? Because they are represented a certain way in memory? If,
somewhere in the bowels of read, comments were already represented as
objects and then discarded, wouldn't that invalidate your distinction?
More importantly, as I pointed out earlier, quote is not inviolate.
It is respected by eval, but user code can mutate its contents.
(Example given earlier in the thread). More pointedly, user code can
already remove lists beginning with the symbol 'comment from quotes;
ditto other proposed syntaxes. So whatever you're trying to avoid
with quote is already part of Lisp.
--
Tom Breton, http://world.std.com/~tob
Ugh-free Spelling (no "gh") http://world.std.com/~tob/ugh-free.html
Kent M Pitman <······@world.std.com> writes:
> Tom Breton <···@world.std.com> writes:
>
> > ;;(This object)
> >
> > cannot presently be quoted. If you don't want to consider comments
> > objects, then there still wouldn't be a forbidden object.
>
> It doesn't need to be quoted. It is not an object.
Well, I answered all 3 positions you could take: it {is, isn't, isn't
but would be} an object.
> But if you make
> it a part of the data to be manipulated, then it must be possible to quote.
> All Lisp objects can presently be quoted.
>
> We are looping again.
Yes, we are. I previously pointed out that by "can be quoted", we are
referring to sheltering something thru eval, not thru other code,
which already is impossible to guarantee. You don't seem to
acknowledge that.
> > If, OT3H, you want to call comments not objects now, but objects then,
> > why?
>
> Because it's you that is proposing making them objects. I'm telling you
> what it takes to do that right.
ISTM you're telling me how, if one refuses to admit there are separate
stages, one can end up buggily eval'ing comments. Yes, of course.
That's why there would be stages, which IIRC was the first thing I
said. Similarly with *all sorts of* code, one can rush data
prematurely into eval and make bugs. Thus ISTM your criticism applies
to Lisp as it stands.
If your objection is that the stages would be difficult to sort out,
be mis-executed by old code, something of the like, I've already
answered that.
> There are no polar complex numbers right now, but if you went to add them,
> there are things I'd tell you you had to make those do, too.
> You can't
> say you could just add them "invisibly", which is the claim you've made
> which I am trying to refute.
The claim that I've made that sounds anything like that is that after
winnowing, they'd be gone. This seems irrefutable.
> > More importantly, as I pointed out earlier, quote is not inviolate.
> > It is respected by eval, but user code can mutate its contents.
> > (Example given earlier in the thread). More pointedly, user code can
> > already remove lists beginning with the symbol 'comment from quotes;
> > ditto other proposed syntaxes. So whatever you're trying to avoid
> > with quote is already part of Lisp.
>
> I can't even parse this,
Too bad. I'll sum it up: quote is *already* not inviolate, so your
argument about quote doesn't work.
> but this is not my point at all. My point is that
> if READ returns something, you must be able to quote that result and
> then evaluate it yielding the thing that READ quoted.
> It can't be the case that
> (read)
> and
> (eval `',(read))
> yield different things or you will break things.
I've already answered how vanilla "read" and "eval" and their cousins
would be grandfathered to encompass two stages so as not to break
things.
--
Tom Breton, http://world.std.com/~tob
Ugh-free Spelling (no "gh") http://world.std.com/~tob/ugh-free.html
Well, I'm not hearing any new objections and I think I've answered the
old ones adequately, so I may not have more to say.
Thank you all for the discussion.
--
Tom Breton, http://world.std.com/~tob
Ugh-free Spelling (no "gh") http://world.std.com/~tob/ugh-free.html
Tom Breton <···@world.std.com> writes:
> Well, I'm not hearing any new objections and I think I've answered the
> old ones adequately, so I may not have more to say.
>
> Thank you all for the discussion.
I'm gonna have to amend that. Once I quit wrestling with some
people's (no offense intended) panicky reactions to the idea and had a
little time to think, I realized that one major issue had never even
come up:
It's easy enuff to represent comments in a list and winnow them later,
but what about elsewhere? Do comments in a vector take up slots, and
do the other elements "slide down" when it is winnowed? Worse, how
can comments in a cons cell even be represented? Can a dotted pair
like ( A . &comment "Can we read this?" C ) even be read?
IMO the general answer is that non-list representations would have to
be represented as lists in state 2, and resolved when winnowing.
Which is to say, a fair amount of reader functionality would have to
move into winnow itself. This is an unfortunate development, because
it would require more coding effort than it originally seemed to.
I still believe that it's desirable to represent comments in a way
that can be mechanically handled without much extra effort, meaning
they should be written and read as Lisp objects. And I still believe
the 3 stages is the best way to think about managing comments, and
that existing 'read should be thaut of as (winnow
(read-but-dont-winnow ...))
--
Tom Breton, http://world.std.com/~tob
Ugh-free Spelling (no "gh") http://world.std.com/~tob/ugh-free.html
On Tue, 27 Jul 1999 22:12:37 GMT, Tom Breton <···@world.std.com>
wrote:
>, I realized that one major issue had never even
>come up:
> [snip]
Been there.
| From: Tim Bradshaw <···@tfeb.org>
| Newsgroups: comp.lang.lisp
| Subject: Re: Comments, was Re: Parentheses Hierarchy
| Date: 21 Jul 1999 08:25:08 +0100
| Message-ID: <···············@lostwithiel.tfeb.org>
|
| [snip]
|
| I think you just do a walk removing the comment objects before you
| evaluate. A much more interesting problem is something like this:
|
| #(1 ; ehem
| 2 3)
|
| which would mean you'd have to read #(...) as something that would get
| turned into an array later on, by the thing that stripped the comments
| I guess.
Tom Breton <···@world.std.com> writes:
> Well, I'm not hearing any new objections and I think I've answered the
> old ones adequately, so I may not have more to say.
>
> Thank you all for the discussion.
There is at least one objection I haven't seen you address:
What does this gain you over just adding a new function
READ-INCLUDING-COMMENTS? (Without changing anything else)
[Erik Naggum asked this first, though in other words]
Stig Hemmer,
Jack of a Few Trades.
Stig Hemmer <····@pvv.ntnu.no> writes:
> Tom Breton <···@world.std.com> writes:
>
> > Well, I'm not hearing any new objections and I think I've answered the
> > old ones adequately, so I may not have more to say.
> >
> > Thank you all for the discussion.
>
> There is at least one objection I haven't seen you address:
>
> What does this gain you over just adding a new function
> READ-INCLUDING-COMMENTS? (Without changing anything else)
>
> [Erik Naggum asked this first, though in other words]
This suggestion entirely adresses my objection, since this function
by its choice of a name that the system compiler and other existing
programs don't call, can't injure any existing programs.
Tom Breton <···@world.std.com> writes:
> ;;(This object)
>
> cannot presently be quoted. If you don't want to consider comments
> objects, then there still wouldn't be a forbidden object.
It doesn't need to be quoted. It is not an object. But if you make
it a part of the data to be manipulated, then it must be possible to quote.
All Lisp objects can presently be quoted.
We are looping again.
> If, OT3H, you want to call comments not objects now, but objects then,
> why?
Because it's you that is proposing making them objects. I'm telling you
what it takes to do that right.
There are no polar complex numbers right now, but if you went to add them,
there are things I'd tell you you had to make those do, too. You can't
say you could just add them "invisibly", which is the claim you've made
which I am trying to refute.
> More importantly, as I pointed out earlier, quote is not inviolate.
> It is respected by eval, but user code can mutate its contents.
> (Example given earlier in the thread). More pointedly, user code can
> already remove lists beginning with the symbol 'comment from quotes;
> ditto other proposed syntaxes. So whatever you're trying to avoid
> with quote is already part of Lisp.
I can't even parse this, but this is not my point at all. My point is that
if READ returns something, you must be able to quote that result and
then evaluate it yielding the thing that READ quoted.
It can't be the case that
(read)
and
(eval `',(read))
yield different things or you will break things.
Hi,
·······@home.se (Vilhelm Sj�berg) writes:
> This concern aside, I have another doubt regarding all this. How is
> this new stage, when the code is read in, but the comments not yet
> sifted, to be made available to the programmer? Redefining read to
> return comment-forms as well as proper code would break programs which
> do not expect them. On the other hand, creating a new procedure to
> return that form would be no stronger then simply adding a new
> procedure (definable in terms of read-char) to the standard library,
> and thus this makes a language chage seem unnessesary. Finally, giving
> the programmer _no_ acces to this stage opens up the old "If a tree
> falls in the woods...". =)
This thread about reading in comments via READ make me think about a
related topic:
When compiling a file and a message needs to be printed, it is useful
to mention the specific line and partial contents relevant to the
message. How to get at that? READ looses this information.
It's quite similar to being able to refer to comments in the source.
One solution has been to have READ return what I call an annotated
structure containing for each object within the structure
supplementary information about the file position, line number and
partial structural contents (like CMUCL prints nicely). These
annotations would be invisible to the normal processing,
macroexpansion etc.
I can't remember what programming language (somewhere in the semi-
functional ballpark) had a "widen" operation that supported adding and
removing such context dependent data when finished (the winnow stage).
So, how do compilers refer to specific source file locations except
for the obvious pipelined processing which allows to peek the current
input streams file position -- which now sounds like a hack?
Especially that FILE-POSITION will already been at the end of an
subexpression that lead to the message: its beginning would be more
useful.
Thanks for your attention,
J"org H"ohle
Telekom Research Center -- SW-Reliability
Joerg-Cyril Hoehle <············@tzd.dont.telekom.spam.de.me> wrote:
+---------------
| One solution has been to have READ return what I call an annotated
| structure containing for each object within the structure
| supplementary information about the file position, line number and
| partial structural contents (like CMUCL prints nicely). These
| annotations would be invisible to the normal processing, macroexpansion etc.
+---------------
Shriram Krishnamurthi's "McMicMac" Parser and "Zodiac" source-correlating
macro-expander (included as part of the MrSpidey debugger component of
DrScheme) do *exactly* this, IIRC. See:
http://www.cs.rice.edu/CS/PLT/packages/doc/m3/index.htm
specifically:
http://www.cs.rice.edu/CS/PLT/packages/doc/m3/node4.htm
http://www.cs.rice.edu/CS/PLT/packages/doc/m3/node7.htm
+---------------
| So, how do compilers refer to specific source file locations except
| for the obvious pipelined processing which allows to peek the current
| input streams file position -- which now sounds like a hack?
+---------------
See above...
-Rob
-----
Rob Warnock, 8L-855 ····@sgi.com
Applied Networking http://reality.sgi.com/rpw3/
Silicon Graphics, Inc. Phone: 650-933-1673
1600 Amphitheatre Pkwy. FAX: 650-933-0511
Mountain View, CA 94043 PP-ASEL-IA
············@tzd.dont.telekom.spam.de.me (Joerg-Cyril Hoehle) writes:
> When compiling a file and a message needs to be printed, it is useful
> to mention the specific line and partial contents relevant to the
> message. How to get at that? READ looses this information.
It's possible to write versions of READ that do not lose this information,
and that (for example) hash such information. That works in most cases
(not symbols, because they are interned).
(setf (gethash subform *comment-table*)
(list :file filename :line line-number))
Moon wrote some tools like this for the Lisp Machine for use in various
programs that translate old syntactic forms to newer ones during system
upgrades (e.g., flavors=>clos). It seemed to work fine.
Also, of course, it gets you pretty darned close if you just record the
expression position. It's popular to say line numbers, but if you just
record the paren depth and position as in (3 2 7 4) to mean
(nth 4 (nth 7 (nth 2 (nth 3 x))))
you're going to end up pretty darned close.
Probably most languages record line numbers because they haven't any
better kind of structure. Some lines being complicated, though, I've
found line number to often not be enough and would have been happy for
a [more precise] structural position.
Tom Breton <···@world.std.com> writes:
> Kent M Pitman <······@world.std.com> writes:
>
> > Tom Breton <···@world.std.com> writes:
> >
> > > State two: The code is lists, vectors, etc, including comments.
> > > Stage two: Winnow it.
> > >
> > > State three: The code is lists, vectors, etc, without
> > > comments. Exactly the same as you get now.
> >
> > No, not exactly the same as you get now. Right now, *any* object can be
> > quoted. QUOTE's arguments are an inviolate space that nothing enters.
> > You seek to change it
>
> No, in the status quo, comments already are removed from quotes.
No, that's not so. In the status quo I can choose between notating objects
in a program-visible way or a program-invisible way. Your mechanism would
force it to be the case that certain objects could never be notated in a
program visible way because those objects would be removed if I tried to
make them program-visible.
That is, if ;x becomes (comment x), the problem isn't that I can't
write (foo ;x
)
any more. It's that I can't write (foo (comment x))
any more because your code will be confused and think I'd written
(foo ;x
)
and that I want the (comment x) removed, when perhaps I don't.
> winnowing would be a new stage. I don't know how
> I can make it clearer.
You dno't have to make it any clearer. The point is that you can't add
any new anything invisibly. If the thing has no effect, it doesn't do
anything. If it does something, then it has an effect. If it has an
effect, code must accomodate it. You can't add something cool and not
disrupt everything. That's just the way of the world. And I'm just saying
the disruption is serious and not something I'd ever entertain personally.
> > making it impossible for the language to be properly reflective. Right
> > now, QUOTE is capable of quoting anything that comes out of READ.
>
> Finally an argument about why you would even want quote to do that. I
> feel compelled to point out that aside from this final paragraph, your
> post addressed your own idea, not mine.
>
> However, I don't think that argument works. Already quote is not
> capable of quoting comments, regardless that read looks at them.
Not so. QUOTE is capable of quoting anything I choose to. The problem
with your notation is that you create a kind of object which it will be
impossible to construct myself and put in code becuase something will
get confused and remove it.
> If the fact that there is a stage where comments can be in all sorts
> of places, including inside quote, disturbs you, just think of the
> post-winnowing stage as being the one you want to work with.
No. It's the one you want me to work with. I want to work with the whole
language.
> > You
> > would be punching a big hole in that, and crippling the language's ability
> > to reason about its own data.
>
> Again, after winnowing you have exactly what you have now.
No, it is not.
> And comments aren't going to be mechanically reasoned about anyways,
> and aren't now, so where do you see a problem?
You are violating some important "conservation" properties of the language.
You cannot reason about this by statistical guesses about where people do
and don't want to work. You have to make sure you don't violate much more
fundamental truths.
This will be my last post to you on this matter.
I really have nothing more to say on this.
Kent M Pitman <······@world.std.com> writes:
> Tom Breton <···@world.std.com> writes:
>
> > Kent M Pitman <······@world.std.com> writes:
> >
> > > Tom Breton <···@world.std.com> writes:
> > >
> > > > State two: The code is lists, vectors, etc, including comments.
> > > > Stage two: Winnow it.
> > > >
> > > > State three: The code is lists, vectors, etc, without
> > > > comments. Exactly the same as you get now.
> > >
> > > No, not exactly the same as you get now. Right now, *any* object can be
> > > quoted. QUOTE's arguments are an inviolate space that nothing enters.
> > > You seek to change it
> >
> > No, in the status quo, comments already are removed from quotes.
>
> No, that's not so.
Clearly it is so.
(if
(equal
(quote
;;Quote can quote comments
"Quote cannot quote comments")
'"Quote cannot quote comments")
"Tom is rite"
"Kent is rite")
> In the status quo I can choose between notating objects
> in a program-visible way or a program-invisible way.
You still could. Why wouldn't you?
> Your mechanism would
> force it to be the case that certain objects could never be notated in a
> program visible way because those objects would be removed if I tried to
> make them program-visible.
Such objects already exist. They are called comments. I apologize
for my tone, but after saying this in several ways already, I find
myself a bit frustrated in explaining it. Think of the comments as
comments.
> That is, if ;x becomes (comment x), the problem isn't that I can't
> write (foo ;x
> )
> any more. It's that I can't write (foo (comment x))
> any more because your code will be confused and think I'd written
> (foo ;x
> )
> and that I want the (comment x) removed, when perhaps I don't.
Well, don't put code that you want executed in comments. I don't mean
to be snippy, but why would you?
If this is Vilhelm's point about the exact representation as
(comment ...) confusing people and breaking old code, that's just a
representation issue. Would you still be unsatisfied if the symbol
you couldn't use arbitrarily was "setq" or "quote"?
If this is a point about not being able to introduce the comment
symbol itself, I remind you of the pre-winnowing state, and that this
thread started with your reply to the proposal of a non-winnowing
macro variant. (Which I now think was probably redundant, but that's
another issue)
> > winnowing would be a new stage. I don't know how
> > I can make it clearer.
>
> You dno't have to make it any clearer. The point is that you can't add
> any new anything invisibly. If the thing has no effect, it doesn't do
> anything. If it does something, then it has an effect.
And as with many things in Lisp, we can alter stuff before telling
eval about it.
> > However, I don't think that argument works. Already quote is not
> > capable of quoting comments, regardless that read looks at them.
>
> Not so. QUOTE is capable of quoting anything I choose to.
Sorry, this is clearly wrong, and already argued some half dozen
times. It's as if you're contradicting me just for the sake of being
contrary, and it's getting tiresome.
> The problem
> with your notation is that you create a kind of object which it will be
> impossible to construct myself and put in code becuase something will
> get confused and remove it.
For a moment there I thaut you were making an argument about not being
able to construct comments at all (See above). But "something will
[properly] remove it."? That already happens with all comments.
> > If the fact that there is a stage where comments can be in all sorts
> > of places, including inside quote, disturbs you, just think of the
> > post-winnowing stage as being the one you want to work with.
>
> No. It's the one you want me to work with. I want to work with the whole
> language.
No, you want to throw away comments. You are already working with
only the post-winnowing stage, so how can you say that?
> > And comments aren't going to be mechanically reasoned about anyways,
> > and aren't now, so where do you see a problem?
>
> You are violating some important "conservation" properties of the language.
Not a one of which you have mentioned. I would be more than happy to
discuss that, but there has to be more to it than simply asserting
that quote can quote comments.
--
Tom Breton, http://world.std.com/~tob
Ugh-free Spelling (no "gh") http://world.std.com/~tob/ugh-free.html
From: Erik Naggum
Subject: Re: Comments, was Re: Parentheses Hierarchy
Date:
Message-ID: <3141970431547512@naggum.no>
* Kent Pitman
| Your mechanism would force it to be the case that certain objects could
| never be notated in a program visible way because those objects would be
| removed if I tried to make them program-visible.
* Tom Breton
| Such objects already exist. They are called comments. I apologize for
| my tone, but after saying this in several ways already, I find myself a
| bit frustrated in explaining it. Think of the comments as comments.
consider a list (foo bar zot), where one of the elements is present in
one interpretation of the list and absent in another. what determines
whether it be present or not? in your design, the evaluator determines
whether the element is present. Kent objects to that. I have suggested
that you use two different READ functions, one which returns the list
with that element, and one which doesn't, because it would be necessary
to deal with the element in code, and so it would be necessary for the
evaluator to be able to deal with that object, not just excise it.
incidentally, you would need a comment object that is a bit more complex:
it needs to know the column at which it starts, the number of semi's if
you don't do that as part of the comment string, and whether it was a
#|...|#-style or a ;-style comment. an editor would need to know the
exact location on the line of every form, not just comments, however, and
it seems awfully na�ve to believe that the only thing you'd need to get
this right would be to retain comments in the flow of the other data.
Tom, it's a bad idea. it has been tried, and it was garbage collected.
#:Erik
--
suppose we blasted all politicians into space.
would the SETI project find even one of them?
Erik Naggum <····@naggum.no> writes:
> incidentally, you would need a comment object that is a bit more complex:
> it needs to know the column at which it starts, the number of semi's if
> you don't do that as part of the comment string, and whether it was a
> #|...|#-style or a ;-style comment.
Worse, it needs to understand:
( \f\o\o ;<-- I used this notation because I hate the other notation
)
and it needs to understand:
( FO0BAR
;^shouldn't this be an "o"?
)
and it needs to understand:
;v-- this is here to remind me visually of the carriage return
"foo\
bar"
That is, it needs to be text through and through.
READ-LINE and friends already exist for this purpose.
Erik Naggum <····@naggum.no> writes:
> * Kent Pitman
> | Your mechanism would force it to be the case that certain objects could
> | never be notated in a program visible way because those objects would be
> | removed if I tried to make them program-visible.
>
> * Tom Breton
> | Such objects already exist. They are called comments. I apologize for
> | my tone, but after saying this in several ways already, I find myself a
> | bit frustrated in explaining it. Think of the comments as comments.
>
> consider a list (foo bar zot), where one of the elements is present in
> one interpretation of the list and absent in another. what determines
> whether it be present or not?
All sorts of code does that now. EG, (list (nth 0 lis) (nth 2 lis))
> in your design, the evaluator determines
> whether the element is present.
Excuse me? Whether the code is winnowed determines whether the
comment is present.
Similarly, in the ~status quo~ passing code thru eg (ignore ...)
before eval'ing it determines whether elements are present.
Generally, and in all old code, it would be winnowed. Read and its
friends would be grandfathered to encompass both reading and
winnowing. Ditto eval. When you wanted to manipulate comments, you
would use the bare read-but-dont-winnow and eval-but-dont-winnow.
> I have suggested
> that you use two different READ functions, one which returns the list
> with that element, and one which doesn't, because it would be necessary
> to deal with the element in code,
Yes, this is essentially the idea of grandfathering read and eval to
include the winnowing stage, and naming the basic manipulations
read-but-dont-winnow, winnow, and eval-but-dont-winnow. (The names
are mere suggestions)
> and so it would be necessary for the
> evaluator to be able to deal with that object, not just excise it.
Excising it gives you what you get now, so I see no problem.
> incidentally, you would need a comment object that is a bit more complex:
> it needs to know [a lot of stylistic data]
As I see it, you would simply pp it. You wouldn't even need to change
pp, tho I'm sure there'd be demand for that.
I see pp'd code and data every day. It may not beat hand-formatted
code, but a) at least in emacs, most comments are mechanically
formatted anyways, and b) code transformation is useful even if the
comments are sub-optimally formatted.
--
Tom Breton, http://world.std.com/~tob
Ugh-free Spelling (no "gh") http://world.std.com/~tob/ugh-free.html
From: Tim Bradshaw
Subject: Re: Comments, was Re: Parentheses Hierarchy
Date:
Message-ID: <nkj3dybk6ug.fsf@tfeb.org>
Erik Naggum <····@naggum.no> writes:
> incidentally, you would need a comment object that is a bit more complex:
> it needs to know the column at which it starts, the number of semi's if
> you don't do that as part of the comment string, and whether it was a
> #|...|#-style or a ;-style comment. an editor would need to know the
> exact location on the line of every form, not just comments, however, and
> it seems awfully na�ve to believe that the only thing you'd need to get
> this right would be to retain comments in the flow of the other data.
>
You do need to remember the number of semis &c. If you believe in the
one-true-structure-editing way though, you can rely on having a smart
pretty printer to deal with laying stuff out. I think my
comment-reader ignored #| #| comments altogether (as did the D-machine
one I think, at least it didn't handle them elegantly).
I seem to be saying this a lot recently, but anyone who wants to think
about this stuff should have a look at the interlisp-d environment
which did all this. Although it's hard, and perhaps impossible now,
you need to actually spend some time using it, to see where the
problems are. Attempts to do all this from theory will just end up
reinventing the same slightly broken wheel.
--tim
From: Erik Naggum
Subject: Re: Comments, was Re: Parentheses Hierarchy
Date:
Message-ID: <3141980284975855@naggum.no>
* Tim Bradshaw <···@tfeb.org>
| I seem to be saying this a lot recently, but anyone who wants to think
| about this stuff should have a look at the interlisp-d environment which
| did all this. Although it's hard, and perhaps impossible now, you need
| to actually spend some time using it, to see where the problems are.
| Attempts to do all this from theory will just end up reinventing the same
| slightly broken wheel.
I would say dealing with comments in SGML and HTML has exactly the same
issues associated with them. HTML, for instance, should have made all
elements say outright that their contents should be rendered or ignored
if not understood. (RTF got that part right, amazingly.) since it
doesn't, people had to reinvent the moronic idea of using comments to
carry scripts and other meaningful stuff outside HTML proper. they could
have used processing instructions, but the morons who wrote HTML browsers
couldn't read a specification, so didn't handle it. so now we have a
mechanism that requires comments to be read as part of the data, possibly
to be interpreted or extracted at a lower layer, just like Tom is
proposing for comments in Common Lisp, and it predictably sucks in the
same way and for the same reasons that making comments into objects in
Lisp predictably sucks.
other uses of comments in stupid languages include directives to lint and
various compilers, the use of structured comments to embed documentation
with code, and ways to carry meta-information where none is otherwise
available and then writing processors to deal with the meta-information.
is there anything to be learned from this at all, I wonder. if anything,
it is that comments should be left alone as a devise for human readers of
the code, and should not be processed or even made available to programs
that don't expressly deal with human readers of code, such as editors.
it is a serious mistake to believe that comments are objects in the code.
if you want that, use documentation strings or invent a _proper_ way to
annotate your code or data structures or whatnot.
bottom line is: if you think using comments is a solution to anything, it
can only be because comments are already supported and you think they
aren't doing any good, so you can make them do something good, but this
is a really, really stupid view, and anyone who makes it learns the hard
way that using comments for anything other than communication with human
readers of the code is just as stupid as adorning any other feature in
the language with an unintended meaning, such as letting variable names
carry encoded type information. solve the right problem, don't think you
can use whatever you find to kluge up a solution.
sometimes, when I read about all these reinvented broken wheels, I think
of what incredible genius it took to think up the wheel and what stamina
that creator must have had in the face of "helpful" suggestions from his
peers. I wonder if it's possible to patent the concept of the broken
wheel and sue stupid people for patent infringement. sigh.
#:Erik
--
suppose we blasted all politicians into space.
would the SETI project find even one of them?
From: Lars Marius Garshol
Subject: Re: Comments, was Re: Parentheses Hierarchy
Date:
Message-ID: <wkpv1fsgy0.fsf@ifi.uio.no>
* Erik Naggum
|
| I would say dealing with comments in SGML and HTML has exactly the
| same issues associated with them.
This was my reaction to this debate also. And in fact I think the
issue goes beyond just comments. With markup languages it is common
separate between the lexical and logical views of the document. In the
latter you only know the structure of the document, in the former you
care about such things as whitespace in tags, comments, entity
structure etc
This can be applied to source code as well. The compiler doesn't care
about whitespace, comments, which file a line of code came from, how
characters were represented inside a string etc etc An editor, on the
other hand, needs to retain all this information in order to avoid
screwing up the code.
--Lars M.
From: Tim Bradshaw
Subject: Re: Comments, was Re: Parentheses Hierarchy
Date:
Message-ID: <nkjr9lvsgve.fsf@tfeb.org>
Erik Naggum <····@naggum.no> writes:
> I would say dealing with comments in SGML and HTML has exactly the same
> issues associated with them. HTML, for instance, should have made all
> elements say outright that their contents should be rendered or ignored
> if not understood. (RTF got that part right, amazingly.) since it
> doesn't, people had to reinvent the moronic idea of using comments to
> carry scripts and other meaningful stuff outside HTML proper. they could
> have used processing instructions, but the morons who wrote HTML browsers
> couldn't read a specification, so didn't handle it. so now we have a
> mechanism that requires comments to be read as part of the data, possibly
> to be interpreted or extracted at a lower layer, just like Tom is
> proposing for comments in Common Lisp, and it predictably sucks in the
> same way and for the same reasons that making comments into objects in
> Lisp predictably sucks.
>
Can processing instructions occur *anywhere* in SGML text? I suspect there are niggling restrictions like:
<foo a="bar" <?pi>>
not being legal (forgive me if I have forgotten too much SGML syntax).
In fact, can comments occur anywhere?
I've just sort-of realised that Lisp already has the mechanism you
probably need for comments. #+.
(if x
#+Comment
#S(comment :semis 2 :text "this is a comment, I can read it")
foo
bar)
You might want to choose a more obscure feature than `comment' I
guess, and this still doesn't solve the comment-in-literal-structure
issue (but neither does the other suggestion), you need to change the
readtable for that.
--tim
From: Lars Marius Garshol
Subject: Re: Comments, was Re: Parentheses Hierarchy
Date:
Message-ID: <wkoggzsfxk.fsf@ifi.uio.no>
* Erik Naggum
|
| they could have used processing instructions, but the morons who
| wrote HTML browsers couldn't read a specification, so didn't handle
| it. so now we have a mechanism that requires comments to be read as
| part of the data, possibly to be interpreted or extracted at a lower
| layer, [...]
* Tim Bradshaw
|
| Can processing instructions occur *anywhere* in SGML text? I
| suspect there are niggling restrictions like:
|
| <foo a="bar" <?pi>>
|
| not being legal (forgive me if I have forgotten too much SGML syntax).
| In fact, can comments occur anywhere?
Nope. Comments can only occur inside declarations. <!-- ... --> is in
fact an empty declaration. Declarations can occur anywhere outside
other constructs, just like processing instructions and tags.
However, with declarations and tags there are restrictions on which
ones can occur where.
| I've just sort-of realised that Lisp already has the mechanism you
| probably need for comments. #+.
|
| (if x
| #+Comment
| #S(comment :semis 2 :text "this is a comment, I can read it")
| foo
| bar)
|
| You might want to choose a more obscure feature than `comment' I
| guess, and this still doesn't solve the comment-in-literal-structure
| issue (but neither does the other suggestion), you need to change the
| readtable for that.
I think I prefer using a separate reader, as suggested by Erik. When
you care about comments you probably care about other information
thrown away by the reader as well. Using a special syntax (even if
acceptable to the normal reader) doesn't sound very good, nifty though
the proposal is.
--Lars M.
From: Erik Naggum
Subject: Re: Comments, was Re: Parentheses Hierarchy
Date:
Message-ID: <3141984684438577@naggum.no>
* Tim Bradshaw <···@tfeb.org>
| Can processing instructions occur *anywhere* in SGML text?
no.
| In fact, can comments occur anywhere?
no.
#:Erik, who's trying to forget...
--
suppose we blasted all politicians into space.
would the SETI project find even one of them?
Erik Naggum <····@naggum.no> writes:
> * Tim Bradshaw <···@tfeb.org>
> | Can processing instructions occur *anywhere* in SGML text?
> no.
> | In fact, can comments occur anywhere?
> no.
Nor in lisp. You can't put comments in strings, for example.
And why? Because the creators of all Lisps (rightly) have decided that this
would require crossing abstraction layers that should not be crossed.
We could say that ";" comments are stripped out before the text is
processed for semantics, and so could have semicolon comments in strings.
But we don't, because that would mean an inability to quote arbitrary text
in strings, including comments, and that is a higher priority. So there
are even examples of this decision having been made once already in Lisp.
That's not to say you can't create a device that pre-processes Lisp and
hands it stuff with meta-notations stripped out. Just that that's not
part of Lisp, and so it's not, for example, part of the READ/EVAL model.
Erik Naggum <····@naggum.no> writes:
>
> bottom line is: if you think using comments is a solution to anything, it
> can only be because comments are already supported and you think they
> aren't doing any good, so you can make them do something good, but this
> is a really, really stupid view, and anyone who makes it learns the hard
> way that using comments for anything other than communication with human
> readers of the code is just as stupid as adorning any other feature in
> the language with an unintended meaning, such as letting variable names
> carry encoded type information.
I have never suggested in any way that comments should carry any
additional information. I say they should not be lost during
mechanical transformation.
--
Tom Breton, http://world.std.com/~tob
Ugh-free Spelling (no "gh") http://world.std.com/~tob/ugh-free.html
From: Erik Naggum
Subject: Re: Comments, was Re: Parentheses Hierarchy
Date:
Message-ID: <3142044283494830@naggum.no>
* Tom Breton <···@world.std.com>
| I have never suggested in any way that comments should carry any
| additional information.
which is the very definition of additional information, since comments
carry exactly zero information to the READ function.
| I say they should not be lost during mechanical transformation.
READ is the wrong function for mechanical transformation of source code,
but the right function for mechanical transformation of parsed source
code. I really don't see why you keep not getting this distinction. is
it because you perchance do not understand what READ does and that Lisp
source code is _not_ stored as text? nah, that just _can't_ be.
incidentally, speaking of mechanical transformation, one of my pet peeves
with Emacs is that M-^ (delete-indentation) does not understand comments.
consider
...) ;blargh
)))
and try to lift the closing parens up to the preceding line with M-^.
it becomes
...) ;blargh)))
which is wrong, but if comments are structured objects and we have:
...)))) ;blargh
the comment is now at a different location in the tree, and if this was
the end of a top-level form, the comment is strictly speaking not part of
the top-level form, anymore. somehow, humans don't have a problem with
that, which suggests that comments are extrastructural, or floating in
the source.
in the SGML world, which you're trying to reinvent for Lisp, we had
floating elements, too, called "inclusion exceptions". the best way to
deal with them was to take them out of the source tree and just remember
where they were while hanging them on another tree. this was how they
were intended to be used, for things like figures, anchors for indices
and hypertext, etc, etc, so it wasn't a problem until somebody wanted to
use them to "fix" "broken" DTDs. then we realized what a horrible
mistake it was not to say outright that they were not part of the
structure. but it would equally be a mistake to require them to be
placed elsewhere, with explicit anchor points in the structure, so the
general concensus emerged that they should never be used for fixing DTDs,
only for extrastructural elements.
I think I have to write a book, "Know SGML, Forget SGML", and I wonder if
it should have a subtitle like "some unforgettable lessons".
#:Erik
--
suppose we blasted all politicians into space.
would the SETI project find even one of them?
Erik Naggum <····@naggum.no> writes:
> I think I have to write a book, "Know SGML, Forget SGML", and I wonder if
> it should have a subtitle like "some unforgettable lessons".
I think I'd be among the first buyers. It seems to me that the
computing community is generally more in need of these kind of
"negative" books, than the huge amount of "XXXX - the ultimate answer
to all your problems" books that are increasingly produced. Many
"new" ideas are old ideas, that either turned out to be bad ideas or
difficult to implement correctly. But instead of acknowledging this
fact, and trying to first learn from the past, before inventing yet
another ultimate tool/method/theory/..., we go on as if everything old
has been erased, and "invent" new things every two seconds.
If our field could be judged by the contents of it's books, it would
seem that we have already solved every problem. If you look at
reality, things seem a trifle different...
Regs, Pierre.
--
Pierre Mai <····@acm.org> PGP and GPG keys at your nearest Keyserver
"One smaller motivation which, in part, stems from altruism is Microsoft-
bashing." [Microsoft memo, see http://www.opensource.org/halloween1.html]
From: William Deakin
Subject: Re: Comments, was Re: Parentheses Hierarchy
Date:
Message-ID: <379F009D.E93D3999@pindar.com>
"Pierre R. Mai" wrote:
> If our field could be judged by the contents of it's books, it would seem that
> we have already solved every problem. If you look at reality, things seem a
> trifle different...
So you wouldn't be interested in down loading my Universal Problems Solver? Its
very like the General Problem Solver but also answers all the major philosophical
questions of the day and can guess you weight! all written in Visual C++ 7.9 with
EFC (the Epistemological Foundation Classes :-)
Cheers,
:-) will
Erik Naggum wrote: [1999-07-27 06:04 +0000]
[...]
> incidentally, speaking of mechanical transformation, one of my pet peeves
> with Emacs is that M-^ (delete-indentation) does not understand comments.
> consider
>
> ...) ;blargh
> )))
>
> and try to lift the closing parens up to the preceding line with M-^.
> it becomes
>
> ...) ;blargh)))
>
> which is wrong, but if comments are structured objects and we have:
>
> ...)))) ;blargh
>
> the comment is now at a different location in the tree, and if this was
> the end of a top-level form, the comment is strictly speaking not part of
> the top-level form, anymore. somehow, humans don't have a problem with
> that, which suggests that comments are extrastructural, or floating in
> the source.
[...]
This is also another example which shows that just having the
character macro definition of #\; produce (COMMENT "blargh")
(or #<comment "blargh"> or whatever) is bad also for the reason
that
(form
...)))) ;blargh
is *not* the same as
(form
...))))
;blargh
but such a macro definition would make the two indistinguishable. E.g.
consider:
(let ((foo val))
...
(bar baz quux)) ;BAR ensures that the returned value is frobnicated
versus
(let ((foo val))
...
(bar baz quux))
;now all foos have been processed
(ignoring for the moment that the latter comment actually needs
a double semicolon).
Vassil Nikolov
Permanent forwarding e-mail: ········@poboxes.com
For more: http://www.poboxes.com/vnikolov
Abaci lignei --- programmatici ferrei.
Tom Breton <···@world.std.com> writes:
> State one: The code is sitting there being ASCII.
> Stage one: Read it.
>
> State two: The code is lists, vectors, etc, including comments.
> Stage two: Winnow it.
>
> State three: The code is lists, vectors, etc, without
> comments. Exactly the same as you get now.
>
> Stage three: Eval it. Or compile it, or call a macro and eval the
> result, etc. Anything along the lines of "now do what the code says"
> goes here.
Fine, so macros don't see comments. Old macros still work.
> For code transformations, it would go:
>
> State one: The code is sitting there being ASCII.
> Stage one: Read it.
>
> State two: The code is lists, vectors, etc, including comments.
> Stage two: Transform it, managing the comments as appropriate to your
> transformation.
So what do you think a code transformation is? Most that I have
written were macros. OK, you could provide additional interfaces for
defining and invoking these new comment-preserving transformations,
but that's only half the problem. In order to transform code, you
have to understand it, and the way code transformers understand random
macros is to expand them. But macros don't know about these new
comment objects, so the transformer has to winnow them out before
expansion, and then it can't put them back in because it doesn't know
where. And winnowing is recursive, it must descend all the way down
(*), because it can't know which parts the macro is going to look at.
So these new comments get lost if they're physically inside a macro
call -- such as LET or DEFUN! This isn't very useful.
(*) "all the way down" is a problematic concept in the presence of
user read macros. How do you know whether you need to look inside
some random data structure? However, circular #= has similar
problems, and we live with it.
--
Pekka P. Pirinen
(the new) Harlequin Limited
All that glitters has a high refractive index.
·····@harlequin.co.uk (Pekka P. Pirinen) writes:
> Tom Breton <···@world.std.com> writes:
>
> > For code transformations, it would go:
> >
> > State one: The code is sitting there being ASCII.
> > Stage one: Read it.
> >
> > State two: The code is lists, vectors, etc, including comments.
> > Stage two: Transform it, managing the comments as appropriate to your
> > transformation.
>
> So what do you think a code transformation is?
What I mean here is turning one form of human-readable code into
another form of human-readable code. There was an example, not even
mine, on the other thread.
> written were macros. OK, you could provide additional interfaces for
> defining and invoking these new comment-preserving transformations,
> but that's only half the problem.
> In order to transform code, you
> have to understand it, and the way code transformers understand random
> macros is to expand them. But macros don't know about these new
> comment objects, so the transformer has to winnow them out before
> expansion,
Yes, this is why I suggested an additional type of macro, that would
differ only in that its parm list would not be winnowed.
> And winnowing is recursive, it must descend all the way down
> (*), because it can't know which parts the macro is going to look at.
> So these new comments get lost if they're physically inside a macro
> call -- such as LET or DEFUN! This isn't very useful.
You have a point: Sorting out when to start winnowing is an issue.
One could say that the contents (not the parms) of all macros are
winnowed when they are defined. Usually this does what is wanted,
because the comments in something that you call are usually not
relevant.
It would appear at first that this doesn't let macros construct new
code that includes comments, which could be useful. But one could use
the new type of macro to introduce 'em.
> (*) "all the way down" is a problematic concept in the presence of
> user read macros. How do you know whether you need to look inside
> some random data structure? However, circular #= has similar
> problems, and we live with it.
Funny you should say that. I just added circular #N= to emacs. As
you say, you must be sure not to forget about places you need to look
in -- I forgot about text properties until RMS reminded me. But it's
perfectly doable.
--
Tom Breton, http://world.std.com/~tob
Ugh-free Spelling (no "gh") http://world.std.com/~tob/ugh-free.html
* Mike McDonald wrote:
> Would you really want
> (if (eq a b)
> ; I really want this to be done when a == b
> (do-something))
> to turn into
> (if (eq a b)
> (comment "I really want this to be done when a == b")
> (do-something))
> Lots of forms would have to become "comment aware" to keep everything
> working. Writing a new macro, for instance, would become a lot more
> complicated. Heck, most of us don't handle doc strings in our macros
> as it is.
No this isn't the problem. You can trivially get rid of the comments
just after reading them. A much harder problem is the:
#(1 2 ;comment
3)
thing. This means that either your preliminary comment-stripper needs
to be able to walk arbitrary objects which is a pain (and expensive,
and not really possible in any case), or all the read-macros need to
turn into forms that only later on create the objects they represent.
I have no idea if the D-machines did this right, but I suspect they
did not.
--tim
Samir Barjoud <·····@mindspring.com> writes:
> Tom Breton <···@world.std.com> writes:
>
> > Which brings me to another topic, for which I expect to be roundly
> > flamed. The comment syntax in Lisp is suboptimal. It doesn't survive
> > reformatting -- even emacs can screw up comment-vs-code when you
> > reformat (ie, when you fill-paragraph).
>
> `fill-paragraph' works ok on code that contains embedded comments.
> How does emacs screw it up?
For instance, write this...
;;Some comments
(a-little-code)
and move the point to at the beginning of the second line, the code.
M-q. The "code" is now at the end of the comments and won't be seen.
(for 20.2.1 anyways).
> Comments
> are the only information (other than whitespace) lost upon READing.
And whitespace can be recovered to some degree by pp.
> How would the following be handled?
>
> (setq residents-of-McWorld
> '(RonaldMcDonald ;; is the head honcho.
> Grimace ;; is purple.
> Birdie ;; loves to fly.
> ))
No, that'd be wrong either way. After read and before eval, the
comments should be removed, so eval never sees "is the head honcho"
etc.
--
Tom Breton, http://world.std.com/~tob
Ugh-free Spelling (no "gh") http://world.std.com/~tob/ugh-free.html
Tom Breton <···@world.std.com> writes:
> > `fill-paragraph' works ok on code that contains embedded comments.
> > How does emacs screw it up?
>
> For instance, write this...
>
> ;;Some comments
> (a-little-code)
>
> and move the point to at the beginning of the second line, the code.
> M-q. The "code" is now at the end of the comments and won't be seen.
> (for 20.2.1 anyways).
Hmmm, in XEmacs (20.4) I can't seem to get M-q to screw up the code,
no matter where I put the point... What am I doing wrong?
Regs, Pierre.
--
Pierre Mai <····@acm.org> PGP and GPG keys at your nearest Keyserver
"One smaller motivation which, in part, stems from altruism is Microsoft-
bashing." [Microsoft memo, see http://www.opensource.org/halloween1.html]
In article <··············@orion.dent.isdn.cs.tu-berlin.de>,
····@acm.org (Pierre R. Mai) writes:
> Tom Breton <···@world.std.com> writes:
>
>> > `fill-paragraph' works ok on code that contains embedded comments.
>> > How does emacs screw it up?
>>
>> For instance, write this...
>>
>> ;;Some comments
>> (a-little-code)
>>
>> and move the point to at the beginning of the second line, the code.
>> M-q. The "code" is now at the end of the comments and won't be seen.
>> (for 20.2.1 anyways).
>
> Hmmm, in XEmacs (20.4) I can't seem to get M-q to screw up the code,
> no matter where I put the point... What am I doing wrong?
>
> Regs, Pierre.
>
In Xemacs 19.16, using Franz' CL interface (the version that came with
ACL4.2), it messes up.
Mike McDonald
·······@mikemac.com
From: William Deakin
Subject: Re: Comments, was Re: Parentheses Hierarchy
Date:
Message-ID: <3796DC41.95993CB2@pindar.com>
Samir Barjoud wrote:
> How would the following be handled?
>
> (setq residents-of-McWorld
> '(RonaldMcDonald ;; is the head honcho.
> Grimace ;; is purple.
> Birdie ;; loves to fly.
> ))
>
> Or is this enough proof that the idea is flawed?
I think this idea is flawed beacuse you want comments in the first place. I
have alot of bitter personal experience of code that has been commented,
then altered and the comments not updated. Particularly as comments are not
compiled or interpreted their meaning (or lack of it) cannot not be
verified.
There is a big problem with legacy code and code maintenance and I believe
(and have seen no evidence to the contrary) that the idea that lots of
comments will help with either development or support work is seriously
flawed. Please take the following with as much salt as you would like: I
remember reading somewhere that research on legacy systems has shown that on
average 75% of the comments in code were either misleading and in some cases
just plain wrong after 3 years of maintainance. But, could you imagine
working on a system where 75% of the code didn't compile? or 75% of the code
was seriously flawed in some other way? All code written in Visual C++
excluded, of course ;-)
CL has documentation strings which are a true wonder to behold, so why not
use these! Keep these updated and use comments very sparing if at all.
I'm aware that my views on comments are somewhat contriversial, to the point
where I have had shouting matches about this. And I would also like to sing
from the same hymn sheet as everybody else but I would like to be sure that
this is wrong first,
:-) will
'Basically, avoid comments. If you code needs a comment to be understood, it
would be better to rewrite to make it easier to understand.' -- Robert Pike
'Comments on data are usually more helpful than on algorithms' -- Robert
Pike (what a wise man)
In article <·················@pindar.com>,
William Deakin <········@pindar.com> wrote:
>Samir Barjoud wrote:
>
>I think this idea is flawed beacuse you want comments in the first place. I
>have alot of bitter personal experience of code that has been commented,
>then altered and the comments not updated. Particularly as comments are not
>compiled or interpreted their meaning (or lack of it) cannot not be
>verified.
>
In one of my first jobs in the field, I was given some large assembly-
language programs and told not to look at the comments because they
were misleading. I did not do well at that job.
>There is a big problem with legacy code and code maintenance and I believe
>(and have seen no evidence to the contrary) that the idea that lots of
>comments will help with either development or support work is seriously
>flawed.
I will suggest that there are different kinds of comments. Comments
are valuable for outlining the whole idea behind a group of functions,
and this is a lot less likely to change than the details of a given
function. The lowest level of comment that I think is likely to be
useful is the documentation string or similar, and I'm not so sure
about that.
I can usually find my way around a large C++ program without comments
here where I'm working. The important part is that the variable and
function and class names are meaningful, and I know the language
well enough to read it easily. I could speculate on the comparative
difficulty of doing this in an equivalent Common Lisp program, but it
hardly seems necessary in c.l.l.
>CL has documentation strings which are a true wonder to behold, so why not
>use these! Keep these updated and use comments very sparing if at all.
>
The documentation string is a function-level comment, usually short.
Meaningful function and variable names are a must also. Give me those
and I can manage.
Oh, and let's not forget the potential of comments to clutter up the page.
I like to work in 48-line windows for C++, and that's none too large.
I do my CL work on a system with a much smaller monitor.
>'Basically, avoid comments. If you code needs a comment to be understood, it
>would be better to rewrite to make it easier to understand.' -- Robert Pike
>
I'd disagree with this as a general statement, but it's useful since
there's so many books arguing on the other side. Put in a "usually"
and I'd agree completely, and it would lose some of its impact.
>'Comments on data are usually more helpful than on algorithms' -- Robert
>Pike (what a wise man)
>
Agreed.
--
David H. Thornley | If you want my opinion, ask.
·····@thornley.net | If you don't, flee.
http://www.thornley.net/~thornley/david/ | O-
From: William Deakin
Subject: Re: Comments, was Re: Parentheses Hierarchy
Date:
Message-ID: <37984F7D.808EF2D9@pindar.com>
I apologise if you get a repeat of this but I am having problems with my
newserver at the mo' :-|
David Thornley wrote:
> I will suggest that there are different kinds of comments. Comments are
> valuable for outlining the whole idea behind a group of functions, and this is
> a lot less likely to change than the details of a given function.
This is very true. Comments should say what or why something happens and not how
because functions most often change in implementation details but not in what
they do.
> The lowest level of comment that I think is likely to be useful is the
> documentation string or similar, and I'm not so sure about that.
But if you use a documentation string wisely you get roll you own documentations.
This may not be a concern for many but when the Man calls for documentation there
are times I curse the inability of a language like C, say, to extract comments.
> ... The important part is that the variable and function and class names are
> meaningful ....The documentation string is a function-level comment, usually
> short. Meaningful function and variable names are a must also. Give me those
> and I can manage ...
I think this is very important and I could not agree more. Call something like a
variable or function something meaningful. Rather than:
QxxYYodf (pingo pongo) ;this calculates the first 37 terms of the continued
fraction pingo/pongo
What about:
calc-37-cfraction-terms (numerator denominator)
> I could speculate on the comparative difficulty of doing this in an equivalent
> Common Lisp program, but it hardly seems necessary in c.l.l.
What? I don't understand.
> Oh, and let's not forget the potential of comments to clutter up the page.
Please let's not. This and unecessary lines are the bugbear of my life. But maybe
I should get out more :-)
> I like to work in 48-line windows for C++, and that's none too large. I do my
> CL work on a system with a much smaller monitor.
48 lines! give me 24x80, vi and a monochrome green vt100 :-)
OK then.
'Basically, avoid comments if you can. If your code needs a comment to be
understood, usually it would be better to rewrite to make it easier to
understand. Write comments and documentation strings to say what and why
something happens and not how. You must use meaningful variable and function
names. And please try to keep things simple.'
It's not a pithy but I'm thinking about selling this to Baz Lerman for a follow
up to 'sunscreen'. Do you a 50% cut of the royalties? ;-)
Best Regards,
:-) will
William Deakin wrote:
> 'Basically, avoid comments. If you code needs a comment to be understood, it
> would be better to rewrite to make it easier to understand.' -- Robert Pike
Some things are difficult to understand without comments, even
when the code has been clarified as much as possible. And, when
you're skimming through code rather than reading it, it's
quicker to read the comments than to read the code; most of
us read natural languages faster than programming languages.
> 'Comments on data are usually more helpful than on algorithms' -- Robert
> Pike (what a wise man)
That one's spot on, yes.
--
Gareth McCaughan ················@pobox.com
sig under construction
From: William Deakin
Subject: Re: Comments, was Re: Parentheses Hierarchy
Date:
Message-ID: <37982C4B.A7C4791A@pindar.com>
Gareth McCaughan wrote:
> Some things are difficult to understand without comments, even when the code has
> been clarified as much as possible.
Fair point. But please don't use this as an excuse to not simplify stuff if you
can.
On a number of occasions where I have looked at somebody elses code, I have gone
to the person who wrote the code 'whats going on here?' they've said 'look the
comments, they explain it all.' I've gone ok. Read the comments, read the code and
then finally got some understanding of whats going on.
<rant>But in my opinion, in all these cases the code was so unecessarily confused
or obstruse that the author would have been better rewriting the stuff rather than
documenting, with comments, the ham fisted botch they had made in the first
place.</rant>
Was Einstein who said somethings about keeping things simple as possible, but no
simpler?
> And, when you're skimming through code rather than reading it, it's quicker to
> read the comments than to read the code; most of us read natural languages
> faster than programming languages.
Yup. But what if the comments are wrong because the code has been changed but the
comments haven't ... reading natural language that is wrong is slower than reading
the code :-(
:-) will
William Deakin wrote:
[me:]
>> Some things are difficult to understand without comments, even when
>> the code has been clarified as much as possible.
>
> Fair point. But please don't use this as an excuse to not simplify
> stuff if you can.
I wouldn't dream of it.
> On a number of occasions where I have looked at somebody elses code,
> I have gone to the person who wrote the code 'whats going on here?'
> they've said 'look the comments, they explain it all.' I've gone
> ok. Read the comments, read the code and then finally got some
> understanding of whats going on.
> <rant>But in my opinion, in all these cases the code was so
> unecessarily confused or obstruse that the author would have been
> better rewriting the stuff rather than documenting, with comments,
> the ham fisted botch they had made in the first place.</rant>
Sure.
> Was Einstein who said somethings about keeping things simple as
> possible, but no simpler?
I think so. There's a bit of my brain saying "Pauli", but I think
it's wrong.
>> And, when you're skimming through code rather than reading it, it's
>> quicker to read the comments than to read the code; most of us read
>> natural languages faster than programming languages.
>
> Yup. But what if the comments are wrong because the code has been
> changed but the comments haven't ... reading natural language that
> is wrong is slower than reading the code :-(
So don't write wrong comments, and don't update commented code
without changing the comments. This *should* be as obvious as
e.g. "don't update a .c file without keeping its .h file in step",
but unfortunately compilers aren't yet intelligent enough to give
warning messages like
foo.lisp, line 100: comment doesn't accurately describe behaviour of code.
Alas, alas.
I conjecture that the programmers who will write code clear enough
not to need comments if you ask them to are also the programmers who
will keep their comments accurate if you ask them to. So saying
"don't use comments, because inaccurate comments are a disaster"
doesn't work. If accurate comments aren't an option, neither is
code that doesn't need comments. And I'd rather have sloppily
commented junk than uncommented junk; wouldn't you? (In either
case the first thing I'd do if given the chance would be to clean
up both code and comments.)
--
Gareth McCaughan ················@pobox.com
sig under construction
From: Lars Marius Garshol
Subject: Re: Comments, was Re: Parentheses Hierarchy
Date:
Message-ID: <wk90865ri8.fsf@ifi.uio.no>
* Gareth McCaughan
|
| but unfortunately compilers aren't yet intelligent enough to give
| warning messages like
|
| foo.lisp, line 100: comment doesn't accurately describe behaviour
| of code.
|
| Alas, alas.
I would expect that when compilers get this good you would be able to
forget all about comments and instead do
(query #'foo "What does it do?")
and get the result
"The function foo frobnosticates its arguments, provided that ..."
Indeed, it shouldn't be too far from the day when you can say
(write-function 'foo "Should frobnosticate its arguments provided
that ...")
And right now I'd be rather happy if I had this function and its
companion write-thesis since I could then finally get out of here and
enjoy the summer.
--Lars M.
Lars Marius Garshol wrote:
> Indeed, it shouldn't be too far from the day when you can say
>
> (write-function 'foo "Should frobnosticate its arguments provided
> that ...")
>
> And right now I'd be rather happy if I had this function and its
> companion write-thesis since I could then finally get out of here and
> enjoy the summer.
I've often been mildly surprised that Emacs doesn't have M-x write-thesis.
--
Gareth McCaughan ················@pobox.com
sig under construction
On Thu, 22 Jul 1999 09:54:25 +0100, William Deakin wrote:
>I think this idea is flawed beacuse you want comments in the first place. I
>have alot of bitter personal experience of code that has been commented,
>then altered and the comments not updated. Particularly as comments are not
>compiled or interpreted their meaning (or lack of it) cannot not be
>verified.
Not commenting is as wrong as comments that echo the code. Comments
should echo the design, not the implementation; that way when the code
changes the comments are still valid.
When the design changes, of course, you throw away the code. :-)
>CL has documentation strings which are a true wonder to behold, so why not
>use these! Keep these updated and use comments very sparing if at all.
This is a very good way to handle it -- docstrings are almost always used
to communicate design. It's hard to abuse them.
>:-) will
>'Basically, avoid comments. If you code needs a comment to be understood, it
>would be better to rewrite to make it easier to understand.' -- Robert Pike
Pike, I suspect, was talking about implementation comments rather than
design comments.
--
-William "Billy" Tanksley
> William Tanksley wrote:
>
> Not commenting is as wrong as comments that echo the code. Comments
> should echo the design, not the implementation; that way when the code
> changes the comments are still valid.
OK. But are comments in the code the right place to put this kind of
information? If the Man (or anybody else) wants to see the design surely
a set of comments isn't the right place for this information. What about
a separate design document? It would be good if you could get at this
information and this is why I do like documentation strings.
> When the design changes, of course, you throw away the code. :-)
Oh so true.
>> CL has documentation strings which are a true wonder to behold, so
>> why not use these! Keep these updated and use comments very sparing
>> if at all.
>
> This is a very good way to handle it -- docstrings are almost always
> used to communicate design. It's hard to abuse them.
>
> 'Basically, avoid comments. If your code needs a comment to be
> understood, it would be better to rewrite to make it easier to
> understand.' -- Robert Pike
(I must apologise to El Pike for my typo :-()
> Pike, I suspect, was talking about implementation comments rather than
> design comments.
Please could you tell me what is the difference?
Also I was in a bookshop in York on the weekend had a read of the new
book by Kernigan and Pike. This has interesting things to say about
commenting. But as it was the end the month I was too poor to buy :-(
Cheers,
:-) will
Sent via Deja.com http://www.deja.com/
Share what you know. Learn what you don't.
On Wed, 28 Jul 1999 10:51:09 GMT, ········@my-deja.com wrote:
>> William Tanksley wrote:
>> Not commenting is as wrong as comments that echo the code. Comments
>> should echo the design, not the implementation; that way when the code
>> changes the comments are still valid.
>OK. But are comments in the code the right place to put this kind of
>information?
Yes. They aren't the primary place, but they do serve well as a guide
during implementation.
Quite often the 'final' step of detailed design is to write out a
step-by-step version of the algorithm, as an enumerated list. This
enumerated list is copied into the source file, and the desired function
is then written chunk by chunk and item by item around the commented list.
>If the Man (or anybody else) wants to see the design surely
>a set of comments isn't the right place for this information. What about
>a separate design document?
This is, of course, the primary place.
>It would be good if you could get at this
>information and this is why I do like documentation strings.
Right. Another good thing about docstrings is that they're available with
the compiled code, so you can read about it without having to load the
source. This can also be handy for automated tests -- if you've got a
standard format, you can describe the test in the doctring and an
autotester can be set up to cruise through and run the tests.
You can't do that with comments, or even with C-style asserts.
>> When the design changes, of course, you throw away the code. :-)
>Oh so true.
And yet oh so false (sigh). I hate to imagine all the time I've "saved" by
reusing old code for a new design... But there was little choice, the new
code HAD to run by a certain time, and there wasn't enough slack for a
rewrite. I paid for my rush in later debugging time -- but the rush job
did pay off, because the code was ready to test the chip when it was
shipped.
>>> CL has documentation strings which are a true wonder to behold, so
>>> why not use these! Keep these updated and use comments very sparing
>>> if at all.
>> This is a very good way to handle it -- docstrings are almost always
>> used to communicate design. It's hard to abuse them.
>> 'Basically, avoid comments. If your code needs a comment to be
>> understood, it would be better to rewrite to make it easier to
>> understand.' -- Robert Pike
>(I must apologise to El Pike for my typo :-()
>> Pike, I suspect, was talking about implementation comments rather than
>> design comments.
>Please could you tell me what is the difference?
(+ i (next-freeble i)) ; add the result of next-freeble to i
That's an implementation comment.
Here's a design comment (shown without code, because it doesn't matter,
and because it's the same as the previous code):
; 3. Index to the next freeble in the zoof-list
Note the itemization -- this is the third step in this algorithm (which
is, BTW, commonly used to determine what percent of all microfleems are
subradantiate).
>:-) will
--
-William "Billy" Tanksley
William Tanksley wrote:
>>> Pike, I suspect, was talking about implementation comments rather than
>>> design comments.
>
>> Please could you tell me what is the difference?
>
> (+ i (next-freeble i)) ; add the result of next-freeble to i
>
> That's an implementation comment.
Does anyone really write comments as uninformative as that?
> Here's a design comment (shown without code, because it doesn't matter,
> and because it's the same as the previous code):
>
> ; 3. Index to the next freeble in the zoof-list
>
> Note the itemization -- this is the third step in this algorithm (which
> is, BTW, commonly used to determine what percent of all microfleems are
> subradantiate).
I would still call that an "implementation comment" if I had to
put it in one of your two classes. My idea of a "design comment"
would be something more like
;; The following function takes a greeble and returns the number
;; of free fleems with at most *FLEEM-LIMIT* degrees of freedom.
;; It does this by walking along the greeble's zoof-list looking
;; for freebles, and therefore takes time proportional to the
;; length of the zoof-list. If you have many subradiante micro-
;; -fleems, you may want to use hash tables instead; in this case
;; you'll need to change the definition of the GREEBLE class.
;; Alternatively, you could hide under your desk.
I'm not saying "You've got the definition wrong, so there", since
I've not heard the exact terms used before. But I think -- well,
I hope -- that ";; add 1 to i" type comments are very rare, in
which case it's more helpful to draw a distinction at a slightly
higher level.
--
Gareth McCaughan ················@pobox.com
sig under construction
On 29 Jul 1999 00:20:03 +0100, Gareth McCaughan wrote:
>William Tanksley wrote:
>>>> Pike, I suspect, was talking about implementation comments rather than
>>>> design comments.
>>> Please could you tell me what is the difference?
>> (+ i (next-freeble i)) ; add the result of next-freeble to i
>> That's an implementation comment.
>Does anyone really write comments as uninformative as that?
Be VERY afraid. Yes, they commonly do -- try reading any available source
code.
>> Here's a design comment (shown without code, because it doesn't matter,
>> and because it's the same as the previous code):
>> ; 3. Index to the next freeble in the zoof-list
>> Note the itemization -- this is the third step in this algorithm (which
>> is, BTW, commonly used to determine what percent of all microfleems are
>> subradantiate).
>I would still call that an "implementation comment" if I had to
>put it in one of your two classes.
The boundary between design and detailed design does sometimes blur, but
this one is clearly a design comment. Observe that it describes a step in
an algorithm -- a "how", not a "what".
Consider that any possible change to the code which that comment describes
could not make the comment invalid without also making the algorithm
invalid. Again, the itemization is also a useful clue.
>My idea of a "design comment" would be something more like
>;; The following function takes a greeble and returns the number
>;; of free fleems with at most *FLEEM-LIMIT* degrees of freedom.
>;; It does this by walking along the greeble's zoof-list looking
>;; for freebles, and therefore takes time proportional to the
>;; length of the zoof-list. If you have many subradiante micro-
>;; -fleems, you may want to use hash tables instead; in this case
>;; you'll need to change the definition of the GREEBLE class.
>;; Alternatively, you could hide under your desk.
You're right; this is also a design comment. What you put into it is very
helpful; I would also include a few use samples. (Actually, I would put
the whole thing in a docstring.) I like the brief overview of the
algorithm and data structure, as well as the mention of the design choices
(although I would say that the design choices belong in a seperate
document; this code's getting deleted if the algorithm changes, and we
don't want to risk making the maintainer think that cutting, pasting, and
modifying your code will be sufficient because you've thought of it in
advance).
But there's still another level of design, the detailed algorithm
description. This is what line-by-line comments are good for.
Another good use of line-by-line comments is justifying messy code --
"This loop structure was chosen because on the HP PA/RISC it takes 50
seconds to complete, while the much cleaner alternative (documented in
so-and-so.tex) takes 100 seconds." That comment skirts the boundaries of
implementation comments, but I would be VERY grateful to see it.
>I'm not saying "You've got the definition wrong, so there", since
>I've not heard the exact terms used before. But I think -- well,
>I hope -- that ";; add 1 to i" type comments are very rare, in
>which case it's more helpful to draw a distinction at a slightly
>higher level.
It's not really a question of magnitude, but of type. I admit that my
specific example of an implementation comment is especially low-level, but
even high level ones are annoying and common.
Heh heh.
(+ 5 (fubar)) ;; assemble "CALL FUBAR", then "ADD 5, %o0, %l0"
Yup, I finally imagined an even WORSE comment than my original example :).
>Gareth McCaughan ················@pobox.com
--
-William "Billy" Tanksley
William Tanksley wrote:
>>> (+ i (next-freeble i)) ; add the result of next-freeble to i
>>> That's an implementation comment.
>
>> Does anyone really write comments as uninformative as that?
>
> Be VERY afraid. Yes, they commonly do -- try reading any available source
> code.
I've read a fair bit of source code of various kinds, and seen
very little that's that bad. But I'll happily (well, not exactly
happily) take your word for it that there's a lot of this kind
of rubbish out there.
>>> ; 3. Index to the next freeble in the zoof-list
>
>>> Note the itemization -- this is the third step in this algorithm (which
>>> is, BTW, commonly used to determine what percent of all microfleems are
>>> subradantiate).
>
>> I would still call that an "implementation comment" if I had to
>> put it in one of your two classes.
>
> The boundary between design and detailed design does sometimes blur, but
> this one is clearly a design comment. Observe that it describes a step in
> an algorithm -- a "how", not a "what".
>
> Consider that any possible change to the code which that comment describes
> could not make the comment invalid without also making the algorithm
> invalid. Again, the itemization is also a useful clue.
I think this depends on what we mean by "algorithm". I'd say it
would still be the same algorithm if you replaced the explicit
stepping with a suitable LOOP or DO, or a magic macro that loops
over the zoof-list of a greeble; in either case there would be
no place for that comment.
>> My idea of a "design comment" would be something more like
>
>> ;; The following function takes a greeble and returns the number
>> ;; of free fleems with at most *FLEEM-LIMIT* degrees of freedom.
>> ;; It does this by walking along the greeble's zoof-list looking
>> ;; for freebles, and therefore takes time proportional to the
>> ;; length of the zoof-list. If you have many subradiante micro-
>> ;; -fleems, you may want to use hash tables instead; in this case
>> ;; you'll need to change the definition of the GREEBLE class.
>> ;; Alternatively, you could hide under your desk.
>
> You're right; this is also a design comment. What you put into it is very
> helpful; I would also include a few use samples. (Actually, I would put
> the whole thing in a docstring.)
I'm glad you like it, but it wasn't in fact intended to be an
example of what good comments should look like; just to show
the sort of thing *I* would call design rather than implementation.
I agree that examples are often useful in comments of this kind,
and I agree that docstrings are a Good Thing. (But I prefer to keep
docstrings brief, and use comments for extended discussions.)
> I like the brief overview of the
> algorithm and data structure, as well as the mention of the design choices
> (although I would say that the design choices belong in a seperate
> document; this code's getting deleted if the algorithm changes, and we
> don't want to risk making the maintainer think that cutting, pasting, and
> modifying your code will be sufficient because you've thought of it in
> advance).
I think the value of having the design decision documented briefly
right next to the code is important. With the code and documentation
widely separated, it's too easy to change one and not the other, and
it's not so easy for someone reading through the code to see what's
going on.
> But there's still another level of design, the detailed algorithm
> description. This is what line-by-line comments are good for.
I'd make them N-lines-by-N-lines, with N varying between about 5
and about 10 most of the time. Most of the code I've seen that
really needs a comment for each line is in assembly language.
> Another good use of line-by-line comments is justifying messy code --
> "This loop structure was chosen because on the HP PA/RISC it takes 50
> seconds to complete, while the much cleaner alternative (documented in
> so-and-so.tex) takes 100 seconds." That comment skirts the boundaries of
> implementation comments, but I would be VERY grateful to see it.
I completely agree.
> (+ 5 (fubar)) ;; assemble "CALL FUBAR", then "ADD 5, %o0, %l0"
Bletch. You should be ashamed of yourself.
++i; /* add 2 to the variable j */
--
Gareth McCaughan ················@pobox.com
sig under construction
From: William Deakin
Subject: Re: Comments, was Re: Parentheses Hierarchy
Date:
Message-ID: <37A16839.E8CA49A@pindar.com>
Gareth McCaughan wrote:
> I've read a fair bit of source code of various kinds, and seen very little
> that's that bad. But I'll happily (well, not exactly happily) take your word
> for it that there's a lot of this kind of rubbish out there.
If us two will's ganged up on you would you take our word more seriously? I have
seen lots and lots of really duff comments :-( (my humble appologies to m.
Tanksley if he doesn't want to be included in this)
> Most of the code I've seen that really needs a comment for each line is in
> assembly language.
Fair point. But this is where sensible naming of variables or functions does not
apply :-(
Then again I would prefur to go out for a weekend of DIY trepanning rather than
write assembly. But horses for courses...
Cheers,
:-) will
William Deakin wrote:
> Then again I would prefur to go out for a weekend of DIY trepanning
> rather than write assembly. But horses for courses...
I should perhaps mention that the only assembly language I've
read or written much of in the last 12 years is for the ARM,
which has possibly the nicest instruction set in the world.
I'd probably prefer sawing my own leg off[1] to writing x86 assembler,
but ARM assembler is actually fun. (Maybe I should seek psychiatric
help.)
[1] As you see, I wouldn't go quite so far as you...
--
Gareth McCaughan ················@pobox.com
sig under construction
On 29 Jul 1999 21:33:53 +0100, Gareth McCaughan wrote:
>William Tanksley wrote:
>>>> ; 3. Index to the next freeble in the zoof-list
>>>> Note the itemization -- this is the third step in this algorithm (which
>>>> is, BTW, commonly used to determine what percent of all microfleems are
>>>> subradantiate).
>>> I would still call that an "implementation comment" if I had to
>>> put it in one of your two classes.
>> The boundary between design and detailed design does sometimes blur, but
>> this one is clearly a design comment. Observe that it describes a step in
>> an algorithm -- a "how", not a "what".
>> Consider that any possible change to the code which that comment describes
>> could not make the comment invalid without also making the algorithm
>> invalid. Again, the itemization is also a useful clue.
>I think this depends on what we mean by "algorithm". I'd say it
>would still be the same algorithm if you replaced the explicit
>stepping with a suitable LOOP or DO, or a magic macro that loops
>over the zoof-list of a greeble; in either case there would be
>no place for that comment.
It is, of course, possible that the detailed design got WAY too detailed
-- but in that case the fault isn't with the comments, but rather with the
design. If anything, the comments serve as a warning.
However, since I put that comment forward as an example of GOOD design, I
now have to justify it -- in this case, that isn't part of a loop. It's
actually a lookahead into the array.
>>> My idea of a "design comment" would be something more like
>>> ;; The following function takes a greeble and returns the number
>>> ;; of free fleems with at most *FLEEM-LIMIT* degrees of freedom.
>>> ;; It does this by walking along the greeble's zoof-list looking
>>> ;; for freebles, and therefore takes time proportional to the
>>> ;; length of the zoof-list. If you have many subradiante micro-
>>> ;; -fleems, you may want to use hash tables instead; in this case
>>> ;; you'll need to change the definition of the GREEBLE class.
>>> ;; Alternatively, you could hide under your desk.
>> You're right; this is also a design comment. What you put into it is very
>> helpful; I would also include a few use samples. (Actually, I would put
>> the whole thing in a docstring.)
>I'm glad you like it, but it wasn't in fact intended to be an
>example of what good comments should look like; just to show
>the sort of thing *I* would call design rather than implementation.
As helpful as it is, it's something that's not essentially a part of the
code. I'd want it there, but it really belongs elsewhere, and putting it
here as well is merely interesting.
>I agree that examples are often useful in comments of this kind,
>and I agree that docstrings are a Good Thing. (But I prefer to keep
>docstrings brief, and use comments for extended discussions.)
This makes sense from the point of view of resource conservation -- any
other reason?
>> I like the brief overview of the
>> algorithm and data structure, as well as the mention of the design choices
>> (although I would say that the design choices belong in a seperate
>> document; this code's getting deleted if the algorithm changes, and we
>> don't want to risk making the maintainer think that cutting, pasting, and
>> modifying your code will be sufficient because you've thought of it in
>> advance).
>I think the value of having the design decision documented briefly
>right next to the code is important. With the code and documentation
>widely separated, it's too easy to change one and not the other, and
>it's not so easy for someone reading through the code to see what's
>going on.
Don't seperate them.
And an alternate design decision, as interesting as it may be, is of no
use to the reader of your code. It might even be a hinderance.
>> But there's still another level of design, the detailed algorithm
>> description. This is what line-by-line comments are good for.
>I'd make them N-lines-by-N-lines, with N varying between about 5
>and about 10 most of the time. Most of the code I've seen that
>really needs a comment for each line is in assembly language.
I didn't mean one for every line :). That would be very scary -- although
I've done that once for code that didn't have a design document. It
actually worked well (although the project sucked).
>> (+ 5 (fubar)) ;; assemble "CALL FUBAR", then "ADD 5, %o0, %l0"
>Bletch. You should be ashamed of yourself.
> ++i; /* add 2 to the variable j */
But try telling that to kids nowadays. They'd think you're lying.
>Gareth McCaughan ················@pobox.com
--
-William "Billy" Tanksley
William Tanksley wrote:
>>>>> ; 3. Index to the next freeble in the zoof-list
..
> It is, of course, possible that the detailed design got WAY too detailed
> -- but in that case the fault isn't with the comments, but rather with the
> design. If anything, the comments serve as a warning.
>
> However, since I put that comment forward as an example of GOOD design, I
> now have to justify it -- in this case, that isn't part of a loop. It's
> actually a lookahead into the array.
And it isn't in a loop? Then obviously I failed to understand
the operation of the surrounding operation. I'll have to have
a look in Knuth's Algorithm F again. :-)
>> I agree that examples are often useful in comments of this kind,
>> and I agree that docstrings are a Good Thing. (But I prefer to keep
>> docstrings brief, and use comments for extended discussions.)
>
> This makes sense from the point of view of resource conservation -- any
> other reason?
Docstrings are for users; comments are for people reading or
modifying the source. (Of course the two categories overlap.)
The user probably doesn't need to know that it would be
interesting to reimplement the function using hash tables
(though I suppose he might want to know the performance
characteristics of the function).
>> I think the value of having the design decision documented briefly
>> right next to the code is important. With the code and documentation
>> widely separated, it's too easy to change one and not the other, and
>> it's not so easy for someone reading through the code to see what's
>> going on.
>
> Don't seperate them.
Well, that's what I was arguing for. I thought you wanted comments
of that sort separated from the code, and put in separate documentation.
> And an alternate design decision, as interesting as it may be, is of no
> use to the reader of your code. It might even be a hinderance.
I completely disagree. When I'm reading a program, I want to
understand what's going on and why. It's easier to understand
a piece of code if I understand how its writer decided on its
structure. So having information about what the programmer was
thinking when the code was written is useful. And, as I say,
I don't like having documentation and code separated by putting
them in different documents. (Unless there's some tool that
lets you link the two documents together flexibly, and navigate
between them in the right way; that might be really good. I
haven't seen such a tool.)
>>> (+ 5 (fubar)) ;; assemble "CALL FUBAR", then "ADD 5, %o0, %l0"
>
>> Bletch. You should be ashamed of yourself.
>> ++i; /* add 2 to the variable j */
>
> But try telling that to kids nowadays. They'd think you're lying.
:-)
--
Gareth McCaughan ················@pobox.com
sig under construction
In article <··············@g.local>, Gareth McCaughan <················@pobox.com> wrote:
> I don't like having documentation and code separated by putting
> them in different documents. (Unless there's some tool that
> lets you link the two documents together flexibly, and navigate
> between them in the right way; that might be really good. I
> haven't seen such a tool.)
I have seen a prototype using CL-HTTP/MCL and Java for
browsing and annotating Lisp code.
Well, you still could be using a Symbolics Lisp Machine
with its Concordia authoring environment. That's
what its documentation have been
written with - a kind of database of documentation
records. For example you can output the
documentation for a Lisp function via m-x Show Documentation
in a type-out window from the editor (Zmacs).
The documentation output gives you mouse sensitive
hypertext. Clicking right on a node (for example
on the Lisp function you just documented) brings
up a menu. There you choose "Edit Record". Now
you are editing your documentation record for this
Lisp function in a markup editor. Here you will
check in your documentation changes via "Add Patch" and
"Finish Patch" (like you would add patches to your
Lisp software system your working on).
On Sat, 31 Jul 1999 18:37:41 +0200, ······@lavielle.com (Rainer Joswig)
wrote:
> Well, you still could be using a Symbolics Lisp Machine
> with its Concordia authoring environment. That's
> what its documentation have been
> written with - a kind of database of documentation
> records. For example you can output the
> documentation for a Lisp function via m-x Show Documentation
> in a type-out window from the editor (Zmacs).
By the way, where does the Genera environment store source code? In text
files? In a database? Something different?
Paolo
--
Paolo Amoroso <·······@mclink.it>
From: Tim Bradshaw
Subject: Re: Comments, was Re: Parentheses Hierarchy
Date:
Message-ID: <nkj1zdmgv69.fsf@tfeb.org>
·······@mclink.it (Paolo Amoroso) writes:
> By the way, where does the Genera environment store source code? In text
> files? In a database? Something different?
>
Text files. When you load stuff it keeps track of what files you
loaded (including file version) and what came from where, so you can
generally edit the definition of anything (*anything*, not just your
sources) with just a keystroke or two. There's a patching mechanism
as well which is integrated with the whole system (It's slightly
limited compared with the full glory of something like CVS -- it
doesn't deal with branches very well, though there are some signs of
support for that in the last commonly-available release (8.3)).
--tim
Tim Bradshaw <···@tfeb.org> writes:
> ·······@mclink.it (Paolo Amoroso) writes:
>
>
> > By the way, where does the Genera environment store source code? In text
> > files? In a database? Something different?
> >
>
> Text files. When you load stuff it keeps track of what files you
> loaded (including file version) and what came from where, so you can
> generally edit the definition of anything (*anything*, not just your
> sources) with just a keystroke or two. There's a patching mechanism
> as well which is integrated with the whole system (It's slightly
> limited compared with the full glory of something like CVS -- it
> doesn't deal with branches very well, though there are some signs of
> support for that in the last commonly-available release (8.3)).
Uh, "source locators" (when turned on) are stored in the compiled file,
I think.
In article <··············@news.mclink.it>, ·······@mclink.it (Paolo Amoroso) wrote:
> By the way, where does the Genera environment store source code? In text
> files? In a database? Something different?
In text files. But the OS has a versioned file system.
So you get
foo:>source>important-code.lisp.1
foo:>source>important-code.lisp.2
...
It has a complicated DEFSYSTEM implementation
where you can load versions of systems.
So you can load for example CL-HTTP
in version 63.15. It would know which files
and which versions of these files belong
to system 63 and then it would load 15 patches
in their most recent versions on top of that.
Though if you edit text files in Zmacs,
things are a bit different from most
others systems (which are using text files)
I know. You could
for example Edit System CL-HTTP 63
and it would load all files into the
Editor. Then you edit a while in those
buffers. After that you could say
Compile Changed Definitions and Zmacs
would know which definitions to compile.
You could also compile a system and
later in Zmacs move through all the
compilation warnings, Zmacs moves to
the problem, you fix those problems and
Zmacs would remove the warnings.
If you are editing a system and you have identified
a problem, you just change the code try it
out in the running system and then you
say Add Patch, Genera inserts a new patch into
the system. Once you are done with all your
patches, you'd say Finish Patch, Genera asks
you a couple of questions (like whether
you want comments, name patch reviewers, send
mail about it, save the buffers, ...) and then
it close the patch, compiles it, etc. Now
you would have a version 63.16.
Often during development you'd just stay in your
editor. By pressing SUSPEND you'll get a typeout
Lisp listener window (a window which comes down from the
top as much as it has content). Since the Lisp
Listener now wants commands or lisp expressions
as input and it can parse back text to objects,
you can click on mouse sensitive expressions in the
Zmacs and they are getting executed in the
typeout window. So you have a "normal" text
editor (the "look") , but the usage (the "feel")
is different.
On 31 Jul 1999 16:18:09 +0100, Gareth McCaughan wrote:
>William Tanksley wrote:
>>>>>> (+ i (next-freeble i))
>>>>>> ; 3. Index to the next freeble in the zoof-list
>> [he asked: isn't that implementation-dependant on what type of loop
>> you're using?]
>> It is, of course, possible that the detailed design got WAY too detailed
>> -- but in that case the fault isn't with the comments, but rather with the
>> design. If anything, the comments serve as a warning.
>> However, since I put that comment forward as an example of GOOD design, I
>> now have to justify it -- in this case, that isn't part of a loop. It's
>> actually a lookahead into the array.
>And it isn't in a loop? Then obviously I failed to understand
>the operation of the surrounding operation. I'll have to have
>a look in Knuth's Algorithm F again. :-)
It's actually F-star-star-k, the third algorithm. Algorithm F doesn't
have the lookahead (and is thus faster for small values of 'zoof').
>>> I agree that examples are often useful in comments of this kind,
>>> and I agree that docstrings are a Good Thing. (But I prefer to keep
>>> docstrings brief, and use comments for extended discussions.)
>> This makes sense from the point of view of resource conservation -- any
>> other reason?
>Docstrings are for users; comments are for people reading or
>modifying the source. (Of course the two categories overlap.)
>The user probably doesn't need to know that it would be
>interesting to reimplement the function using hash tables
>(though I suppose he might want to know the performance
>characteristics of the function).
This is why I would put the reimplementation info in the docs.
>>> I think the value of having the design decision documented briefly
>>> right next to the code is important. With the code and documentation
>>> widely separated, it's too easy to change one and not the other, and
>>> it's not so easy for someone reading through the code to see what's
>>> going on.
>> Don't seperate them.
>Well, that's what I was arguing for. I thought you wanted comments
>of that sort separated from the code, and put in separate documentation.
I do want those comments put in the docs, but I don't want the docs
_widely_ seperated from the code.
>> And an alternate design decision, as interesting as it may be, is of no
>> use to the reader of your code. It might even be a hinderance.
>I completely disagree. When I'm reading a program, I want to
>understand what's going on and why. It's easier to understand
>a piece of code if I understand how its writer decided on its
>structure. So having information about what the programmer was
>thinking when the code was written is useful.
I hope the programmer wasn't thinking about alternate designs while coding
-- that's a nightmare. You, as the maintainer, shouldn't have to think
about the alternates either -- until it's time to discard the old
algorithm and put in a new one. At that time, you DELETE the function,
including all of those comments, and using the documentation, design new
docs which will eventually be used to write the new code.
None of that historical information ever gets seen if it was only placed
in the comments. The comments are dead before they can be used, and in
the way when they're not dead.
>And, as I say,
>I don't like having documentation and code separated by putting
>them in different documents. (Unless there's some tool that
>lets you link the two documents together flexibly, and navigate
>between them in the right way; that might be really good. I
>haven't seen such a tool.)
That's true -- I really like the idea of Literate Programming.
>Gareth McCaughan ················@pobox.com
--
-William "Billy" Tanksley
William Tanksley wrote:
>> Docstrings are for users; comments are for people reading or
>> modifying the source. (Of course the two categories overlap.)
>> The user probably doesn't need to know that it would be
>> interesting to reimplement the function using hash tables
>> (though I suppose he might want to know the performance
>> characteristics of the function).
>
> This is why I would put the reimplementation info in the docs.
Hmm. We seem to be at cross purposes here.
I take it that anyone reading the source code is in the category
of "people who should be given all the information available".
I don't see why that is a reason for putting some information in
a separate document.
>> Well, that's what I was arguing for. I thought you wanted comments
>> of that sort separated from the code, and put in separate documentation.
>
> I do want those comments put in the docs, but I don't want the docs
> _widely_ seperated from the code.
I don't understand what this means. Do you mean that the filename
of whatever contains the documentation shouldn't differ by more than
3 characters from that of whatever contains the source? Or that
the disk the documentation is stored on should be attached to the
same machine as the source? Presumably not, since both these are
silly, but it's not clear what sort of separation you do have in
mind.
>>> And an alternate design decision, as interesting as it may be, is of no
>>> use to the reader of your code. It might even be a hinderance.
>
>> I completely disagree. When I'm reading a program, I want to
>> understand what's going on and why. It's easier to understand
>> a piece of code if I understand how its writer decided on its
>> structure. So having information about what the programmer was
>> thinking when the code was written is useful.
>
> I hope the programmer wasn't thinking about alternate designs while coding
> -- that's a nightmare.
Why is it a nightmare? The programmer should be aware of possible
changes that might have to be made to the code, so that he has the
option of writing the code in such a way as to make those changes
reasonably straightforward. (He might choose not to exercise that
option; consider the slogan "You aren't going to need it" in so-called
Extreme Programming.)
> You, as the maintainer, shouldn't have to think
> about the alternates either
No, but suppose I come across something that manifestly doesn't
scale well. Maybe it's a quirk of my brain; but I'm likely to
be thinking "Hmm, I wonder why they did that". If there's a brief
note explaining why they did that, then I can stop wondering.
> -- until it's time to discard the old
> algorithm and put in a new one. At that time, you DELETE the function,
> including all of those comments, and using the documentation, design new
> docs which will eventually be used to write the new code.
Not necessarily. I might, for instance, rip out about 50% of the
function and fix what remains, and change only those portions of
the comments that actually require changing. I might replace the
function completely but find that the comments can still mostly
stay because they describe the behaviour of the function as viewed
from outside.
> None of that historical information ever gets seen if it was only placed
> in the comments. The comments are dead before they can be used, and in
> the way when they're not dead.
Why are they "in the way"? Comments of the kind I'm thinking of
go before the function, and they're usually only needed for
relatively large functions. So it's not clear to me in what
circumstances they'd be in the way.
>> And, as I say,
>> I don't like having documentation and code separated by putting
>> them in different documents. (Unless there's some tool that
>> lets you link the two documents together flexibly, and navigate
>> between them in the right way; that might be really good. I
>> haven't seen such a tool.)
>
> That's true -- I really like the idea of Literate Programming.
Me too, but it doesn't do what I was just describing. (Possibly
an LP system could be devised that does; that would be nice.)
--
Gareth McCaughan ················@pobox.com
sig under construction
On 01 Aug 1999 13:51:37 +0100, Gareth McCaughan wrote:
>William Tanksley wrote:
>>> Docstrings are for users; comments are for people reading or
>>> modifying the source. (Of course the two categories overlap.)
>>> The user probably doesn't need to know that it would be
>>> interesting to reimplement the function using hash tables
>>> (though I suppose he might want to know the performance
>>> characteristics of the function).
>> This is why I would put the reimplementation info in the docs.
>Hmm. We seem to be at cross purposes here.
>I take it that anyone reading the source code is in the category
>of "people who should be given all the information available".
>I don't see why that is a reason for putting some information in
>a separate document.
They should certainly see all of the information. That doesn't mean they
want to see it all at once! Information on alternate implementations is
something that should be there, but it's not needed to understand what you
did _here_. It might be helpful to understand the design, but not the code.
So we put it with the design.
I keep on bringing up the most common use of re-implementation info like
this -- "what if someone were re-implementing this code"? Well, the first
thing they'd do after reading the design docs and anough of the code to
understand what was wrong (hopefully none of it), they'd delete the code.
Your comments would go unread by the person who needed them most,
specifically because they're in the middle of stuff he can't afford to read.
>>> Well, that's what I was arguing for. I thought you wanted comments
>>> of that sort separated from the code, and put in separate documentation.
>> I do want those comments put in the docs, but I don't want the docs
>> _widely_ seperated from the code.
>I don't understand what this means. Do you mean that the filename
>of whatever contains the documentation shouldn't differ by more than
>3 characters from that of whatever contains the source? Or that
>the disk the documentation is stored on should be attached to the
>same machine as the source? Presumably not, since both these are
>silly, but it's not clear what sort of separation you do have in
>mind.
I have no idea what you meant by "widely seperated". I was quoting you.
You said you didn't want a wide seperation -- at which time you were
talking about documentation-to-code seperation, implying that documents
are always widely seperated from code -- and I said that docs should NEVER
be widely seperated from code.
>>>> And an alternate design decision, as interesting as it may be, is of no
>>>> use to the reader of your code. It might even be a hinderance.
>>> I completely disagree. When I'm reading a program, I want to
>>> understand what's going on and why. It's easier to understand
>>> a piece of code if I understand how its writer decided on its
>>> structure. So having information about what the programmer was
>>> thinking when the code was written is useful.
>> I hope the programmer wasn't thinking about alternate designs while coding
>> -- that's a nightmare.
>Why is it a nightmare? The programmer should be aware of possible
>changes that might have to be made to the code, so that he has the
>option of writing the code in such a way as to make those changes
>reasonably straightforward. (He might choose not to exercise that
>option; consider the slogan "You aren't going to need it" in so-called
>Extreme Programming.)
XP is a wise practice. Thinking of design while you're coding means that
you weren't thinking enough about design BEFORE YOU STARTED CODING. Sorry
for yelling, I got excited ;-). Never, never, NEVER design while coding.
If a single design change happens while you're coding, it's worth
considering throwing away all your code and going back to design.
I've done this, and not regretted it. I've also failed to do this, and
regretted it very much.
>> You, as the maintainer, shouldn't have to think
>> about the alternates either
>No, but suppose I come across something that manifestly doesn't
>scale well. Maybe it's a quirk of my brain; but I'm likely to
>be thinking "Hmm, I wonder why they did that". If there's a brief
>note explaining why they did that, then I can stop wondering.
Of course. I hope to fing high-level discussion about that in the design
docs, clean and clear. Code is not the right place to look for the answer
"why?". Sometimes it's the only place -- that's why I mentioned
optimization comments, as the only exception I'll consider.
>> -- until it's time to discard the old
>> algorithm and put in a new one. At that time, you DELETE the function,
>> including all of those comments, and using the documentation, design new
>> docs which will eventually be used to write the new code.
>Not necessarily. I might, for instance, rip out about 50% of the
>function and fix what remains, and change only those portions of
>the comments that actually require changing. I might replace the
>function completely but find that the comments can still mostly
>stay because they describe the behaviour of the function as viewed
>from outside.
This is, of course, a judgement call -- and you're not hurt at all by the
fact that I discussed the design seperately. (Doing what you suggest is
the most risky choice, and is made worse the more comments were in the
source, since "cut'n'paste" errors become more likely.)
>> None of that historical information ever gets seen if it was only placed
>> in the comments. The comments are dead before they can be used, and in
>> the way when they're not dead.
>Why are they "in the way"? Comments of the kind I'm thinking of
>go before the function, and they're usually only needed for
>relatively large functions. So it's not clear to me in what
>circumstances they'd be in the way.
They'll be in the way more often than the same thing in a doc file.
>>> And, as I say,
>>> I don't like having documentation and code separated by putting
>>> them in different documents. (Unless there's some tool that
>>> lets you link the two documents together flexibly, and navigate
>>> between them in the right way; that might be really good. I
>>> haven't seen such a tool.)
>> That's true -- I really like the idea of Literate Programming.
>Me too, but it doesn't do what I was just describing. (Possibly
>an LP system could be devised that does; that would be nice.)
Actually it does -- but only for the author, not the reader. But then the
author usually knows the best presentation. A good LP viewer would be
helpful, though.
>Gareth McCaughan ················@pobox.com
--
-William "Billy" Tanksley
········@dolphin.openprojects.net (William Tanksley) writes:
> >Extreme Programming.)
>
> XP is a wise practice. Thinking of design while you're coding means that
> you weren't thinking enough about design BEFORE YOU STARTED CODING. Sorry
> for yelling, I got excited ;-). Never, never, NEVER design while coding.
> If a single design change happens while you're coding, it's worth
> considering throwing away all your code and going back to design.
This is, IMHO, overdoing things.
It seems to me like you have elevated a rule of thumb in an absolute.
> I've done this, and not regretted it. I've also failed to do this, and
> regretted it very much.
If you say so...
May I suggest that if you have to scrap your entire program if you do
a single design change, then there is something wrong somewhere?
Stig Hemmer,
Jack of a Few Trades.
On 02 Aug 1999 23:55:19 +0200, Stig Hemmer wrote:
>········@dolphin.openprojects.net (William Tanksley) writes:
>> >Extreme Programming.)
>> XP is a wise practice. Thinking of design while you're coding means that
>> you weren't thinking enough about design BEFORE YOU STARTED CODING. Sorry
>> for yelling, I got excited ;-). Never, never, NEVER design while coding.
>> If a single design change happens while you're coding, it's worth
>> considering throwing away all your code and going back to design.
>This is, IMHO, overdoing things.
>It seems to me like you have elevated a rule of thumb in an absolute.
"Considering", not requiring. Okay, it's a single word in a morass of
yelling :), but I do mean it. Most programmers instinctively want to save
all the code and comments that they can, and only type in a minimal set of
changes. I want to provide a voice against that -- but obviously, one can
conceivably go too far in the other direction. Take my yelling with a
grain of salt, but for heaven's sake, don't think that I'm not serious.
>> I've done this, and not regretted it. I've also failed to do this, and
>> regretted it very much.
>If you say so...
I just did, as a matter of fact. I could (with reference to my books)
quote you numbers, too; but I'm lazy, and arguing is easier :).
>May I suggest that if you have to scrap your entire program if you do
>a single design change, then there is something wrong somewhere?
May I suggest in response that if you fail to _consider_ scrapping your
code there is something seriously wrong?
>Stig Hemmer,
--
-William "Billy" Tanksley
William Tanksley wrote:
> I keep on bringing up the most common use of re-implementation info like
> this -- "what if someone were re-implementing this code"? Well, the first
> thing they'd do after reading the design docs and anough of the code to
> understand what was wrong (hopefully none of it), they'd delete the code.
Maybe "they" would. I wouldn't. I'd leave the old code there until
I had the new code working. Maybe even after that (renamed), for
regression tests or something.
> Your comments would go unread by the person who needed them most,
> specifically because they're in the middle of stuff he can't afford
> to read.
"Can't afford to"? I think I'm missing some point here. Why on earth
would anyone re-implementing something not be able to afford to read
the comments in and around it?
>>>> Well, that's what I was arguing for. I thought you wanted comments
>>>> of that sort separated from the code, and put in separate documentation.
>
>>> I do want those comments put in the docs, but I don't want the docs
>>> _widely_ seperated from the code.
>
>> I don't understand what this means. Do you mean that the filename
>> of whatever contains the documentation shouldn't differ by more than
>> 3 characters from that of whatever contains the source? Or that
>> the disk the documentation is stored on should be attached to the
>> same machine as the source? Presumably not, since both these are
>> silly, but it's not clear what sort of separation you do have in
>> mind.
>
> I have no idea what you meant by "widely seperated". I was quoting you.
Neither have I :-) -- I was about to say "I didn't say `widely'",
but then I took the precaution of checking my words and found that
I had. I wonder what I meant.
> You said you didn't want a wide seperation -- at which time you were
> talking about documentation-to-code seperation, implying that documents
> are always widely seperated from code -- and I said that docs should NEVER
> be widely seperated from code.
I'm inclined to think that anything attached to a specific bit
of code should be as closely tied to that bit of code as possible;
not in a separate document.
I should perhaps qualify that a bit. Obviously it doesn't apply
to documentation that is needed by users who don't need to read
the source. And, equally obviously, it doesn't apply when what
the documentation is really tied to is not the code but (in some
sense) its interface. But I'd say e.g. that anything that refers
to a localised bit of code, and requires knowledge of the internals
of that code, should be kept with the code unless there is a compelling
reason to put it elsewhere instead.
(There certainly can be such reasons; for instance, it might be
helpful to have a list of all places in the program where you've
used implementation-dependent functions.)
My reason for this is that anyone reading such documentation is
going to have to have the code in front of them when they do so;
so the documentation should be placed next to the code.
>>> I hope the programmer wasn't thinking about alternate designs while coding
>>> -- that's a nightmare.
>
>> Why is it a nightmare? The programmer should be aware of possible
>> changes that might have to be made to the code, so that he has the
>> option of writing the code in such a way as to make those changes
>> reasonably straightforward. (He might choose not to exercise that
>> option; consider the slogan "You aren't going to need it" in so-called
>> Extreme Programming.)
>
> XP is a wise practice. Thinking of design while you're coding means that
> you weren't thinking enough about design BEFORE YOU STARTED CODING. Sorry
> for yelling, I got excited ;-). Never, never, NEVER design while coding.
Why does "thinking about alternate designs while coding" imply
"not having thought out the design before coding"?
If I think carefully about the design of something, and decide that
the best data structure somewhere is a linked list but that if X and Y
were different a hash table might be better, why shouldn't I be aware
of the possibility of later change while writing the code? If it was
a difficult decision whether to use the linked list or the hash table
in the first place, why shouldn't I try to design everything so that
it's easy to change later if that proves sensible?
Incidentally, I had the impression that XP was solidly opposed to
the idea of a design phase before coding. Isn't the idea to begin
by coding and take the path of least resistance, and then redesign
bits on the fly (but carefully) when it becomes apparent that
something ought to change?
> If a single design change happens while you're coding, it's worth
> considering throwing away all your code and going back to design.
I'm sure that's true when it's not possible to write the code robustly
enough to accommodate minor design changes. I'm not at all sure that
this is usually the case.
>>> You, as the maintainer, shouldn't have to think
>>> about the alternates either
>
>> No, but suppose I come across something that manifestly doesn't
>> scale well. Maybe it's a quirk of my brain; but I'm likely to
>> be thinking "Hmm, I wonder why they did that". If there's a brief
>> note explaining why they did that, then I can stop wondering.
>
> Of course. I hope to fing high-level discussion about that in the design
> docs, clean and clear. Code is not the right place to look for the answer
> "why?". Sometimes it's the only place -- that's why I mentioned
> optimization comments, as the only exception I'll consider.
How do you distinguish between an "optimization comment" and a
"design comment" that deals with performance issues? I find these
sharp distinctions between categories of comment rather strange.
>>> -- until it's time to discard the old
>>> algorithm and put in a new one. At that time, you DELETE the function,
>>> including all of those comments, and using the documentation, design new
>>> docs which will eventually be used to write the new code.
>
>> Not necessarily. I might, for instance, rip out about 50% of the
>> function and fix what remains, and change only those portions of
>> the comments that actually require changing. I might replace the
>> function completely but find that the comments can still mostly
>> stay because they describe the behaviour of the function as viewed
>> from outside.
>
> This is, of course, a judgement call -- and you're not hurt at all by the
> fact that I discussed the design seperately. (Doing what you suggest is
> the most risky choice, and is made worse the more comments were in the
> source, since "cut'n'paste" errors become more likely.)
It's not more risky; the risks are different. I trade the possibility
of cut-and-paste error against the possibility of something else
going wrong because I reimplemented from scratch and therefore had
less time for other things, and the possibility of making a silly
error while reimplementing the functionality of the old code I could
have reused, and the possibility of missing a subtle point of design
that had been spotted by the writers of the old code. (This last one
isn't quite fair; if it's likely to happen then cut-and-paste is
just as dangerous as rewriting.)
Cut-and-paste has its dangers, but it's by no means an unmitigated
evil. What's evil is copying code without understanding it.
>>> None of that historical information ever gets seen if it was only placed
>>> in the comments. The comments are dead before they can be used, and in
>>> the way when they're not dead.
>
>> Why are they "in the way"? Comments of the kind I'm thinking of
>> go before the function, and they're usually only needed for
>> relatively large functions. So it's not clear to me in what
>> circumstances they'd be in the way.
>
> They'll be in the way more often than the same thing in a doc file.
I don't understand. What are they in the way of?
If you mean that they take up valuable screen acreage, I don't see
why they do so any more than the irrelevant neighbouring bits of
the design docs would under your preferred model.
>>>> And, as I say,
>>>> I don't like having documentation and code separated by putting
>>>> them in different documents. (Unless there's some tool that
>>>> lets you link the two documents together flexibly, and navigate
>>>> between them in the right way; that might be really good. I
>>>> haven't seen such a tool.)
>
>>> That's true -- I really like the idea of Literate Programming.
>
>> Me too, but it doesn't do what I was just describing. (Possibly
>> an LP system could be devised that does; that would be nice.)
>
> Actually it does -- but only for the author, not the reader.
No LP system I know of does what I thought I was describing. In
all of them, the code and documentation are intermingled, or
"in the way" as you put it a little earlier. None of them gives
any easy way of seeing the code and documentation separately,
while maintaining tight links between the two and making it
easy to go from a piece of code to its documentation.
If the LP way of organising code and documentation pleases you,
then I'm not sure why we're arguing. The style of documentation
I'm defending here is pretty much exactly what LP gives you.
--
Gareth McCaughan ················@pobox.com
sig under construction
On 03 Aug 1999 01:16:03 +0100, Gareth McCaughan
<················@pobox.com> wrote:
> No LP system I know of does what I thought I was describing. In
> all of them, the code and documentation are intermingled, or
> "in the way" as you put it a little earlier. None of them gives
> any easy way of seeing the code and documentation separately,
> while maintaining tight links between the two and making it
> easy to go from a piece of code to its documentation.
Have a look at the Scheme Elucidator. It's a literate
programming--actually, an "elucidative programming"--tool developed by Kurt
N�rmark (Aalborg University, Denmark) in the context of the LAML (Lisp
Abstracted Markup Language) project:
http://www.cs.auc.dk/~normark/laml/
By taking advantage of frames, the Elucidator arranges Scheme source code
and documentation side by side in an HTML document with appropriate cross
links. To see an example check the Elucidator demo at the LAML site.
Paolo
--
Paolo Amoroso <·······@mclink.it>
On 03 Aug 1999 01:16:03 +0100, Gareth McCaughan wrote:
>William Tanksley wrote:
>> I keep on bringing up the most common use of re-implementation info like
>> this -- "what if someone were re-implementing this code"? Well, the first
>> thing they'd do after reading the design docs and anough of the code to
>> understand what was wrong (hopefully none of it), they'd delete the code.
>Maybe "they" would. I wouldn't. I'd leave the old code there until
>I had the new code working. Maybe even after that (renamed), for
>regression tests or something.
Okay, I admit that I'm also lax on that particular formality, and I've
never had cause to regret it. I look at the old source code, usually
because the documentation is inadequate.
Regression tests should test your whole system -- it should be the job of
version control to keep the old version acessable. Aegis does a very good
job with this (it also manages regression tests). It can, however, be
very useful to have a cross-test to make sure the output of the old code
matches that of the new.
>> Your comments would go unread by the person who needed them most,
>> specifically because they're in the middle of stuff he can't afford
>> to read.
>"Can't afford to"? I think I'm missing some point here. Why on earth
>would anyone re-implementing something not be able to afford to read
>the comments in and around it?
First because those comments are mixed with code, and they don't want to
read the code (it would be bad to do so). Second because all of the info
in the comments is also contained in the detailed design doc, in a more
accesible format.
>>>>> Well, that's what I was arguing for. I thought you wanted comments
>>>>> of that sort separated from the code, and put in separate documentation.
>>>> I do want those comments put in the docs, but I don't want the docs
>>>> _widely_ seperated from the code.
>>> I don't understand what this means. Do you mean that the filename
>>> of whatever contains the documentation shouldn't differ by more than
>>> 3 characters from that of whatever contains the source? Or that
>>> the disk the documentation is stored on should be attached to the
>>> same machine as the source? Presumably not, since both these are
>>> silly, but it's not clear what sort of separation you do have in
>>> mind.
>> I have no idea what you meant by "widely seperated". I was quoting you.
>Neither have I :-) -- I was about to say "I didn't say `widely'",
>but then I took the precaution of checking my words and found that
>I had. I wonder what I meant.
I'm pretty sure you were making the point that documentation is
inconvenient when you're coding. True, but it's essential when you're
maintaining.
>> You said you didn't want a wide seperation -- at which time you were
>> talking about documentation-to-code seperation, implying that documents
>> are always widely seperated from code -- and I said that docs should NEVER
>> be widely seperated from code.
>I'm inclined to think that anything attached to a specific bit
>of code should be as closely tied to that bit of code as possible;
>not in a separate document.
I really like this philosophy too. I see it the other way, though:
everything tied to a design ought to be accesible from the design
(including the code used to implement the design). I like to tie fewer
things to the code itself, so that if and when the code becomes obsolete
those things don't also.
>I should perhaps qualify that a bit. Obviously it doesn't apply
>to documentation that is needed by users who don't need to read
>the source. And, equally obviously, it doesn't apply when what
>the documentation is really tied to is not the code but (in some
>sense) its interface. But I'd say e.g. that anything that refers
>to a localised bit of code, and requires knowledge of the internals
>of that code, should be kept with the code unless there is a compelling
>reason to put it elsewhere instead.
Thus, implementation choices which weren't chosen certainly don't belong
with the code, because they don't help explain the code itself. They
belong with the design, because they help illustrate it.
>>>> I hope the programmer wasn't thinking about alternate designs while coding
>>>> -- that's a nightmare.
>>> Why is it a nightmare? The programmer should be aware of possible
>>> changes that might have to be made to the code, so that he has the
>>> option of writing the code in such a way as to make those changes
>>> reasonably straightforward. (He might choose not to exercise that
>>> option; consider the slogan "You aren't going to need it" in so-called
>>> Extreme Programming.)
>> XP is a wise practice. Thinking of design while you're coding means that
>> you weren't thinking enough about design BEFORE YOU STARTED CODING. Sorry
>> for yelling, I got excited ;-). Never, never, NEVER design while coding.
>Why does "thinking about alternate designs while coding" imply
>"not having thought out the design before coding"?
It doesn't, really. You got me on that one. Deciding to write those
designs down in the code seems to me to be irrational, though; they're
designs, not code.
>If I think carefully about the design of something, and decide that
>the best data structure somewhere is a linked list but that if X and Y
>were different a hash table might be better, why shouldn't I be aware
>of the possibility of later change while writing the code? If it was
>a difficult decision whether to use the linked list or the hash table
>in the first place, why shouldn't I try to design everything so that
>it's easy to change later if that proves sensible?
If one of your requirements calls for that flexibility, then it's a good
thing. If it doesn't, it's a very bad thing.
>Incidentally, I had the impression that XP was solidly opposed to
>the idea of a design phase before coding. Isn't the idea to begin
>by coding and take the path of least resistance, and then redesign
>bits on the fly (but carefully) when it becomes apparent that
>something ought to change?
That's not what I recall -- but I only read XP once, I don't follow it :).
I'll have to reread it. The development models I'm familiar with which
match what you're describing are the evolutionary model (very dangerous)
and the throwaway prototype model (less dangerous).
My advice to people who decide to change design when they're in the middle
of coding is to consider adopting the throwaway prototype model. If they
decide against that, they'll be adopting the evolutionary model. They
should read up on both models before deciding.
>> If a single design change happens while you're coding, it's worth
>> considering throwing away all your code and going back to design.
>I'm sure that's true when it's not possible to write the code robustly
>enough to accommodate minor design changes. I'm not at all sure that
>this is usually the case.
Possible isn't the question as much as affordable. Is it worth doing
that? Is it worth the effort you're going to spend?
Possibly. Certainly, if the requirements include such.
>>>> You, as the maintainer, shouldn't have to think
>>>> about the alternates either
>>> No, but suppose I come across something that manifestly doesn't
>>> scale well. Maybe it's a quirk of my brain; but I'm likely to
>>> be thinking "Hmm, I wonder why they did that". If there's a brief
>>> note explaining why they did that, then I can stop wondering.
>> Of course. I hope to fing high-level discussion about that in the design
>> docs, clean and clear. Code is not the right place to look for the answer
>> "why?". Sometimes it's the only place -- that's why I mentioned
>> optimization comments, as the only exception I'll consider.
>How do you distinguish between an "optimization comment" and a
>"design comment" that deals with performance issues? I find these
>sharp distinctions between categories of comment rather strange.
Nothing in the code should talk about stuff that's not in the code. That
means no alternate algorithm comments. My exception is that if you write
really ugly code for the sake of speed, be sure to comment on why you
wrote ugly code, and include numbers which prove the effectiveness. That
way, when someone reads the code, they'll know what parts to not attempt
to understand.
>>>> -- until it's time to discard the old
>>>> algorithm and put in a new one. At that time, you DELETE the function,
>>>> including all of those comments, and using the documentation, design new
>>>> docs which will eventually be used to write the new code.
>>> Not necessarily. I might, for instance, rip out about 50% of the
>>> function and fix what remains, and change only those portions of
>>> the comments that actually require changing. I might replace the
>>> function completely but find that the comments can still mostly
>>> stay because they describe the behaviour of the function as viewed
>>> from outside.
>> This is, of course, a judgement call -- and you're not hurt at all by the
>> fact that I discussed the design seperately. (Doing what you suggest is
>> the most risky choice, and is made worse the more comments were in the
>> source, since "cut'n'paste" errors become more likely.)
>It's not more risky; the risks are different. I trade the possibility
>of cut-and-paste error against the possibility of something else
>going wrong because I reimplemented from scratch and therefore had
>less time for other things, and the possibility of making a silly
>error while reimplementing the functionality of the old code I could
>have reused, and the possibility of missing a subtle point of design
>that had been spotted by the writers of the old code. (This last one
>isn't quite fair; if it's likely to happen then cut-and-paste is
>just as dangerous as rewriting.)
In other words, you ADD the risks of cut'n'paste to whatever risks were
already present. That, by definition, is _more_ risky (unless you wish to
argue that cut'n'paste has negative risk).
>Cut-and-paste has its dangers, but it's by no means an unmitigated
>evil. What's evil is copying code without understanding it.
This is true. I didn't claim any moral censure; I'm just pointing out the
risk and making recommendations.
>>>>> And, as I say,
>>>>> I don't like having documentation and code separated by putting
>>>>> them in different documents. (Unless there's some tool that
>>>>> lets you link the two documents together flexibly, and navigate
>>>>> between them in the right way; that might be really good. I
>>>>> haven't seen such a tool.)
>>>> That's true -- I really like the idea of Literate Programming.
>>> Me too, but it doesn't do what I was just describing. (Possibly
>>> an LP system could be devised that does; that would be nice.)
>> Actually it does -- but only for the author, not the reader.
>No LP system I know of does what I thought I was describing. In
>all of them, the code and documentation are intermingled, or
>"in the way" as you put it a little earlier. None of them gives
>any easy way of seeing the code and documentation separately,
>while maintaining tight links between the two and making it
>easy to go from a piece of code to its documentation.
Completely untrue -- in LP the code and design are seperated, but placed
into the same document. Different levels of the design and coding can be
discussed seperately, but they'll be merged by the computer when the time
comes to compile.
Your last sentance is completely contrary to fact -- all LP tools that
I've seen provide definition indexes to allow you to go from a low-level
chunk to any of the high-level chunks that use it, and vice versa.
>If the LP way of organising code and documentation pleases you,
>then I'm not sure why we're arguing. The style of documentation
>I'm defending here is pretty much exactly what LP gives you.
It's the opposite of literate programming -- it mixes design information
into code. LP seperates them in a very convenient and automatically
checkable way.
>Gareth McCaughan ················@pobox.com
--
-William "Billy" Tanksley
William Tanksley wrote:
>> "Can't afford to"? I think I'm missing some point here. Why on earth
>> would anyone re-implementing something not be able to afford to read
>> the comments in and around it?
>
> First because those comments are mixed with code, and they don't want to
> read the code (it would be bad to do so).
It would be bad not to do so.
> Second because all of the info
> in the comments is also contained in the detailed design doc, in a more
> accesible format.
I think this is a circular argument. "You shouldn't put this stuff
in comments, you should put it in seoarate design docs. You should
do this because no one will read the oomments, because all the stuff
in them is also in the separate design docs". Hmmmm.
>> Neither have I :-) -- I was about to say "I didn't say `widely'",
>> but then I took the precaution of checking my words and found that
>> I had. I wonder what I meant.
>
> I'm pretty sure you were making the point that documentation is
> inconvenient when you're coding.
I am absolutely certain that whatever I meant, it wasn't that.
Documentation is essential when you are coding. I just like
having the documentation and code more interleaved than you do.
> Thus, implementation choices which weren't chosen certainly don't belong
> with the code, because they don't help explain the code itself. They
> belong with the design, because they help illustrate it.
They do help explain the code. One rather low-level example: if you
see some horrendous incomprehensible thing where there's an obvious
simple way of achieving what it does, this is confusing. Until you
read the explanation "We tried implementing this as a simple nested
loop, but it was 5 times slower and this is in the inner loop.".
>> Incidentally, I had the impression that XP was solidly opposed to
>> the idea of a design phase before coding. Isn't the idea to begin
>> by coding and take the path of least resistance, and then redesign
>> bits on the fly (but carefully) when it becomes apparent that
>> something ought to change?
>
> That's not what I recall -- but I only read XP once, I don't follow it :).
> I'll have to reread it. The development models I'm familiar with which
> match what you're describing are the evolutionary model (very dangerous)
> and the throwaway prototype model (less dangerous).
What model do you prefer? (You'll have to explain what it means
as well as giving the name. I'm not an expert on the jargon of
software engineering.)
> My advice to people who decide to change design when they're in the middle
> of coding is to consider adopting the throwaway prototype model. If they
> decide against that, they'll be adopting the evolutionary model. They
> should read up on both models before deciding.
"Build one to throw it away. You will anyway." "If you do that, you'll
throw away *two*." :-)
>> How do you distinguish between an "optimization comment" and a
>> "design comment" that deals with performance issues? I find these
>> sharp distinctions between categories of comment rather strange.
>
> Nothing in the code should talk about stuff that's not in the code. That
> means no alternate algorithm comments. My exception is that if you write
> really ugly code for the sake of speed, be sure to comment on why you
> wrote ugly code, and include numbers which prove the effectiveness. That
> way, when someone reads the code, they'll know what parts to not attempt
> to understand.
Right. So you agree with the example I gave earlier. Hooray! Now,
why is this single case so extraordinary as to require completely
opposite treatment from all others?
To my mind, part of "understanding" a piece of code is understanding
why it was written that way. I can do that much better if I have some
idea of what went through the mind of the person who wrote it (or
who designed it, if the tasks were split). So if I read something
and have no idea why they didn't take some particular other approach
that looks better at first sight, I don't really understand the code;
just as I might not really understand some heavily-bummed incomprehensible
maintenance nightmare of the kind you've just instanced. A little
comment along the lines of "We could have done it this way, but
it wouldn't have worked so well" would help.
>> It's not more risky; the risks are different. I trade the possibility
>> of cut-and-paste error against the possibility of something else
>> going wrong because I reimplemented from scratch and therefore had
>> less time for other things, and the possibility of making a silly
>> error while reimplementing the functionality of the old code I could
>> have reused, and the possibility of missing a subtle point of design
>> that had been spotted by the writers of the old code. (This last one
>> isn't quite fair; if it's likely to happen then cut-and-paste is
>> just as dangerous as rewriting.)
>
> In other words, you ADD the risks of cut'n'paste to whatever risks were
> already present. That, by definition, is _more_ risky (unless you wish to
> argue that cut'n'paste has negative risk).
No, you're missing the point. If I cut-and-paste some code that's
known to do some particular task correctly, I DECREASE the risk of
misimplementing that task. Certainly there's an increase in the
risk of that task being subtly mismatched with what's actually
needed, but to say that no risk decreases is simply wrong.
And, if I cut-and-paste some piece of code, I may save time that
I can use in decreasing some other bit of risk. Whether this is a
win or a loss depends on what other risks there are in the code,
and how risky the particular cut-and-paste operation is.
>>>> Me too, but it doesn't do what I was just describing. (Possibly
>>>> an LP system could be devised that does; that would be nice.)
>
>>> Actually it does -- but only for the author, not the reader.
>
>> No LP system I know of does what I thought I was describing. In
>> all of them, the code and documentation are intermingled, or
>> "in the way" as you put it a little earlier. None of them gives
>> any easy way of seeing the code and documentation separately,
>> while maintaining tight links between the two and making it
>> easy to go from a piece of code to its documentation.
>
> Completely untrue -- in LP the code and design are seperated, but placed
> into the same document. Different levels of the design and coding can be
> discussed seperately, but they'll be merged by the computer when the time
> comes to compile.
What do you mean by "the code and design are separated, but placed
into the same document" that doesn't apply equally to code with
design comments in it?
> Your last sentance is completely contrary to fact -- all LP tools that
> I've seen provide definition indexes to allow you to go from a low-level
> chunk to any of the high-level chunks that use it, and vice versa.
You're misunderstanding what I'm saying LP tools don't do.
They don't let you have separate documents (as you advocate)
for code and data, with the sort of links between them that
would negate my arguments for having code and design comments
in the same document.
If you consider the "tangled" output from LP tools to be the
"code document" then we are clearly at cross purposes. That
makes about as much sense to me as would a claim that the
object file produced by a compiler is the "code document".
You aren't supposed to read the "tangled" output of typical
LP tools. You're supposed to read the "woven" document that
contains documentation and code, tightly interwoven.
> It's the opposite of literate programming -- it mixes design information
> into code. LP seperates them in a very convenient and automatically
> checkable way.
In what way is it automatically checkable? And what do you mean
by "separated"?
--
Gareth McCaughan ················@pobox.com
sig under construction
On 06 Aug 1999 00:27:04 +0100, Gareth McCaughan wrote:
>William Tanksley wrote:
>>> "Can't afford to"? I think I'm missing some point here. Why on earth
>>> would anyone re-implementing something not be able to afford to read
>>> the comments in and around it?
>> First because those comments are mixed with code, and they don't want to
>> read the code (it would be bad to do so).
>It would be bad not to do so.
It would be terrible to read code for which you have already designed a
replacement where the new design doesn't match the old. It would be
just evil to NOT read code which you were about to debug.
There's a spectrum between the two, of course.
>> Second because all of the info
>> in the comments is also contained in the detailed design doc, in a more
>> accesible format.
>I think this is a circular argument. "You shouldn't put this stuff
>in comments, you should put it in seoarate design docs. You should
>do this because no one will read the oomments, because all the stuff
>in them is also in the separate design docs". Hmmmm.
I spent quite a bit of time reading this, then examining your past posts.
I think I figured out our problem. I'm assuming the exisitance of a
design document; you're assuming the non-existance.
It's possible that my assumption is wrong; many projects don't need a
design doument, and in those cases all of the things which would otherwise
go in the design document have to be mingled with the code.
However, your assumption is terrible: lack of a design document is a
practical optimization in some cases, but most projects require one (and
most of the projects without design documents would not be hindered by
one). And once you have a design document, the very thought of not
putting every design decision into it is absolutely bizzare.
Now, once you have this document which describes all of your design,
anyone who wants to understand the code will start by reading the document
-- it presents the system organization and layout in a readable form,
without all the little details which code must have in order to run.
Once you've read and understood the document, you'll start working on the
code. You'll want to see in the code little tags which help you remember
which portion of the design you're looking at; this is what I recommend
comments for. The worst possible thing to see is either code which is
hard to read and doesn't appear to match the docs, or code with a comment
which contradicts the docs.
>>> Neither have I :-) -- I was about to say "I didn't say `widely'",
>>> but then I took the precaution of checking my words and found that
>>> I had. I wonder what I meant.
>> I'm pretty sure you were making the point that documentation is
>> inconvenient when you're coding.
>I am absolutely certain that whatever I meant, it wasn't that.
>Documentation is essential when you are coding. I just like
>having the documentation and code more interleaved than you do.
Your idea of documentation is why so many people here dislike comments.
>> Thus, implementation choices which weren't chosen certainly don't belong
>> with the code, because they don't help explain the code itself. They
>> belong with the design, because they help illustrate it.
>They do help explain the code. One rather low-level example: if you
>see some horrendous incomprehensible thing where there's an obvious
>simple way of achieving what it does, this is confusing. Until you
>read the explanation "We tried implementing this as a simple nested
>loop, but it was 5 times slower and this is in the inner loop.".
I have brought up that specific example three times.
>>> Incidentally, I had the impression that XP was solidly opposed to
>>> the idea of a design phase before coding. Isn't the idea to begin
>>> by coding and take the path of least resistance, and then redesign
>>> bits on the fly (but carefully) when it becomes apparent that
>>> something ought to change?
>> That's not what I recall -- but I only read XP once, I don't follow it :).
>> I'll have to reread it. The development models I'm familiar with which
>> match what you're describing are the evolutionary model (very dangerous)
>> and the throwaway prototype model (less dangerous).
>What model do you prefer? (You'll have to explain what it means
>as well as giving the name. I'm not an expert on the jargon of
>software engineering.)
My favorite model is the spiral. I can handle any of the others, and they
all have their place; I just like how the spiral adapts to different
situations, and can even work well with an extremely informal project.
Picture a spiral, starting at a centerpoint. The spiral is a timeline
(bent, of course). Draw a ray starting at the center and heading to the
right. That ray is the start and end of each phase of a project.
Every phase has a name/purpose; it starts with a risk analysis and ends
with a deliverable. The risk analysis is used to give the engineer an
idea of how formal he's going to need to be.
Every project can be inaccurately modeled as a spiral with three phases.
The first phase's "deliverable" is the purpose of the project. The second
phase produces a risk analysis which allows the manager/engineer to decide
what development model to use and how formal to be. The final phase
produces the product itself.
In many projects, the decision has already been made on how formal to be
or which development model to use. It's a temptation to skip that risk
analysis. It's not a good idea.
>> My advice to people who decide to change design when they're in the middle
>> of coding is to consider adopting the throwaway prototype model. If they
>> decide against that, they'll be adopting the evolutionary model. They
>> should read up on both models before deciding.
>"Build one to throw it away. You will anyway." "If you do that, you'll
>throw away *two*." :-)
Agreed. However, in this case I'm recommending that you throw away code
in reaction to a specific event -- design change. I'm not recommending
that you actually plan to throw anything away (although like Brooks, I can
promise that you will :).
>>> How do you distinguish between an "optimization comment" and a
>>> "design comment" that deals with performance issues? I find these
>>> sharp distinctions between categories of comment rather strange.
>> Nothing in the code should talk about stuff that's not in the code. That
>> means no alternate algorithm comments. My exception is that if you write
>> really ugly code for the sake of speed, be sure to comment on why you
>> wrote ugly code, and include numbers which prove the effectiveness. That
>> way, when someone reads the code, they'll know what parts to not attempt
>> to understand.
>Right. So you agree with the example I gave earlier. Hooray! Now,
>why is this single case so extraordinary as to require completely
>opposite treatment from all others?
Because it involves obviously ugly code. The others involve design choices.
>To my mind, part of "understanding" a piece of code is understanding
>why it was written that way. I can do that much better if I have some
>idea of what went through the mind of the person who wrote it (or
>who designed it, if the tasks were split). So if I read something
>and have no idea why they didn't take some particular other approach
>that looks better at first sight, I don't really understand the code;
>just as I might not really understand some heavily-bummed incomprehensible
>maintenance nightmare of the kind you've just instanced. A little
>comment along the lines of "We could have done it this way, but
>it wouldn't have worked so well" would help.
If you read code and think about alternate designs, you need to be whacked
by the Angel of Design. Code isn't design; it's implementation.
I remember a lab partner I had, who partway into the project was reading
my code and said, "why don't we do things a different way? This is
complicated!" Now, think about what he was saying. He had imagined a
clean, pure design, unsullied by code and all the special cases which
arise when coding. He was comparing this to several files full of code,
without attempting to really understand the design behind them.
His design was just as good, and I told him so. However, he was comparing
apples to applecores.
>>> It's not more risky; the risks are different. I trade the possibility
>>> of cut-and-paste error against the possibility of something else
>>> going wrong because I reimplemented from scratch and therefore had
>>> less time for other things, and the possibility of making a silly
>>> error while reimplementing the functionality of the old code I could
>>> have reused, and the possibility of missing a subtle point of design
>>> that had been spotted by the writers of the old code. (This last one
>>> isn't quite fair; if it's likely to happen then cut-and-paste is
>>> just as dangerous as rewriting.)
>> In other words, you ADD the risks of cut'n'paste to whatever risks were
>> already present. That, by definition, is _more_ risky (unless you wish to
>> argue that cut'n'paste has negative risk).
>No, you're missing the point. If I cut-and-paste some code that's
>known to do some particular task correctly, I DECREASE the risk of
>misimplementing that task. Certainly there's an increase in the
>risk of that task being subtly mismatched with what's actually
>needed, but to say that no risk decreases is simply wrong.
We're discussing redesign. If you cut'n'paste code belonging to a
different design, you WILL get cut'n'paste bugs. You WILL spend longer
fixing them than you would have writing new code.
>And, if I cut-and-paste some piece of code, I may save time that
>I can use in decreasing some other bit of risk. Whether this is a
>win or a loss depends on what other risks there are in the code,
>and how risky the particular cut-and-paste operation is.
Right. Some cut'n'paste has lower risk -- that's kind of what macros are.
That's not a zero risk, and it becomes bigger the further out of the
original design the macro is moved.
>>>>> Me too, but it doesn't do what I was just describing. (Possibly
>>>>> an LP system could be devised that does; that would be nice.)
>>>> Actually it does -- but only for the author, not the reader.
>>> No LP system I know of does what I thought I was describing. In
>>> all of them, the code and documentation are intermingled, or
>>> "in the way" as you put it a little earlier. None of them gives
>>> any easy way of seeing the code and documentation separately,
>>> while maintaining tight links between the two and making it
>>> easy to go from a piece of code to its documentation.
>> Completely untrue -- in LP the code and design are seperated, but placed
>> into the same document. Different levels of the design and coding can be
>> discussed seperately, but they'll be merged by the computer when the time
>> comes to compile.
>What do you mean by "the code and design are separated, but placed
>into the same document" that doesn't apply equally to code with
>design comments in it?
Code with design comments mingled is not seperated from the design
information. It's mingled.
LP code is seperated by the author into a full design presentation, down
to the lowest, most detailed level.
>> Your last sentance is completely contrary to fact -- all LP tools that
>> I've seen provide definition indexes to allow you to go from a low-level
>> chunk to any of the high-level chunks that use it, and vice versa.
>You're misunderstanding what I'm saying LP tools don't do.
No.
>They don't let you have separate documents (as you advocate)
>for code and data, with the sort of links between them that
>would negate my arguments for having code and design comments
>in the same document.
Literate programming essentially transforms the entire program into a
design document, but with some parts at a very low level. If the author
is skilled, the result will be far more readable than your average design
document -- and more reliable, because you can be certain that the
implementation matches the design document; they're the same thing.
>If you consider the "tangled" output from LP tools to be the
>"code document" then we are clearly at cross purposes. That
>makes about as much sense to me as would a claim that the
>object file produced by a compiler is the "code document".
>You aren't supposed to read the "tangled" output of typical
>LP tools. You're supposed to read the "woven" document that
>contains documentation and code, tightly interwoven.
You've missed the point of LP. It's not designed to tightly interweave
docs and code (if it was designed for that, someone would have made a
graphical full-screen literate debugger); it's to allow detailed design to
extend to any level of detail by allowing it to be expressed in an
appropriate programming language.
Certain chunks of a literate program -- let's call them the top chunks --
contain the design of the program, in it most sweeping, abstract form.
The reader is introduced to this design as such, in a way which will help
him understand the design. The design is carried out into full detail.
>> It's the opposite of literate programming -- it mixes design information
>> into code. LP seperates them in a very convenient and automatically
>> checkable way.
>In what way is it automatically checkable?
By running 'tangle' on it and compiling.
>And what do you mean by "separated"?
This is a 'top' chunk, a segment of the top-level design. And that, over
at the end of the document or even in an appendix, is some elaboration of
the design -- it happens to implement it. You don't have to understand
the implementation in order to find the design; on the contrary, the
design is presented to you seperately from the implementation.
You seem to think I have a hangup with files. I don't; in fact, like you
I would like it if everything I needed in life was in a single file,
already opened in jed. Unlike you, I would rather have that single file be
organized, so I never would have to search for what I needed next.
;-)
The Author doesn't seem to care what I think, eh? :)
>Gareth McCaughan ················@pobox.com
--
-William "Billy" Tanksley
William Tanksley wrote:
>>> First because those comments are mixed with code, and they don't want to
>>> read the code (it would be bad to do so).
>
>> It would be bad not to do so.
>
> It would be terrible to read code for which you have already designed a
> replacement where the new design doesn't match the old.
It wouldn't be terrible. At the very most it would be unnecessary.
>> I think this is a circular argument. "You shouldn't put this stuff
>> in comments, you should put it in seoarate design docs. You should
>> do this because no one will read the oomments, because all the stuff
>> in them is also in the separate design docs". Hmmmm.
>
> I spent quite a bit of time reading this, then examining your past posts.
> I think I figured out our problem. I'm assuming the exisitance of a
> design document; you're assuming the non-existance.
No, I'm merely non-assuming its existence. :-) But even if there
is a separate design document, I'm in favour of putting some
design information in comments. Even if it's only "See the relevant
section of the detailed design documentation for an explanation of
why this code is the way it is".
> Once you've read and understood the document, you'll start working on the
> code. You'll want to see in the code little tags which help you remember
> which portion of the design you're looking at; this is what I recommend
> comments for. The worst possible thing to see is either code which is
> hard to read and doesn't appear to match the docs, or code with a comment
> which contradicts the docs.
Certainly.
>>>> Neither have I :-) -- I was about to say "I didn't say `widely'",
>>>> but then I took the precaution of checking my words and found that
>>>> I had. I wonder what I meant.
>
>>> I'm pretty sure you were making the point that documentation is
>>> inconvenient when you're coding.
>
>> I am absolutely certain that whatever I meant, it wasn't that.
>> Documentation is essential when you are coding. I just like
>> having the documentation and code more interleaved than you do.
>
> Your idea of documentation is why so many people here dislike comments.
I think this is descending into personal abuse here. You don't
have a clue what "my idea of documentation" is; you've extrapolated
it from a few things I've said. I have some reason to believe that
in at least some cases you have entirely misunderstood. Couldn't
we leave out the "It's because of dimwits like YOU that people don't
approve of comments" stuff?
>>> Nothing in the code should talk about stuff that's not in the code. That
>>> means no alternate algorithm comments. My exception is that if you write
>>> really ugly code for the sake of speed, be sure to comment on why you
>>> wrote ugly code, and include numbers which prove the effectiveness. That
>>> way, when someone reads the code, they'll know what parts to not attempt
>>> to understand.
>
>> Right. So you agree with the example I gave earlier. Hooray! Now,
>> why is this single case so extraordinary as to require completely
>> opposite treatment from all others?
>
> Because it involves obviously ugly code. The others involve design choices.
I'm afraid I don't follow the logic here. Why does ugly code
justify a comment, while other kinds of apparently-bad code don't?
>> To my mind, part of "understanding" a piece of code is understanding
>> why it was written that way. I can do that much better if I have some
>> idea of what went through the mind of the person who wrote it (or
>> who designed it, if the tasks were split). So if I read something
>> and have no idea why they didn't take some particular other approach
>> that looks better at first sight, I don't really understand the code;
>> just as I might not really understand some heavily-bummed incomprehensible
>> maintenance nightmare of the kind you've just instanced. A little
>> comment along the lines of "We could have done it this way, but
>> it wouldn't have worked so well" would help.
>
> If you read code and think about alternate designs, you need to be whacked
> by the Angel of Design. Code isn't design; it's implementation.
A piece of code is the implementation of a design. It contains both
design and implementation. Dogmatic separation of the two is an error,
arising from some people's tendency to confuse the two.
> I remember a lab partner I had, who partway into the project was reading
> my code and said, "why don't we do things a different way? This is
> complicated!" Now, think about what he was saying. He had imagined a
> clean, pure design, unsullied by code and all the special cases which
> arise when coding. He was comparing this to several files full of code,
> without attempting to really understand the design behind them.
>
> His design was just as good, and I told him so. However, he was comparing
> apples to applecores.
I dare say he was. It's not clear to me what your point is.
>> No, you're missing the point. If I cut-and-paste some code that's
>> known to do some particular task correctly, I DECREASE the risk of
>> misimplementing that task. Certainly there's an increase in the
>> risk of that task being subtly mismatched with what's actually
>> needed, but to say that no risk decreases is simply wrong.
>
> We're discussing redesign. If you cut'n'paste code belonging to a
> different design, you WILL get cut'n'paste bugs. You WILL spend longer
> fixing them than you would have writing new code.
You're assuming there's a sharp distinction between reimplementation
and redesign. There isn't. They're the same thing on different levels.
The danger of disasters due to cut-and-paste increases as the level
at which the change occurs gets higher; that's all.
>> What do you mean by "the code and design are separated, but placed
>> into the same document" that doesn't apply equally to code with
>> design comments in it?
>
> Code with design comments mingled is not seperated from the design
> information. It's mingled.
>
> LP code is seperated by the author into a full design presentation, down
> to the lowest, most detailed level.
I simply don't know what you mean by "separated" here.
>>> Your last sentance is completely contrary to fact -- all LP tools that
>>> I've seen provide definition indexes to allow you to go from a low-level
>>> chunk to any of the high-level chunks that use it, and vice versa.
>
>> You're misunderstanding what I'm saying LP tools don't do.
>
> No.
I am not interested in holding a discussion with someone who tells
me what I'm thinking and then flatly refuses to believe me when I
say that he's misunderstood. I'm afraid that my conviction that I
know my mind better than you do is unshakeable.
>> If you consider the "tangled" output from LP tools to be the
>> "code document" then we are clearly at cross purposes. That
>> makes about as much sense to me as would a claim that the
>> object file produced by a compiler is the "code document".
>> You aren't supposed to read the "tangled" output of typical
>> LP tools. You're supposed to read the "woven" document that
>> contains documentation and code, tightly interwoven.
>
> You've missed the point of LP.
You mean: "Your idea of the point of LP differs from mine".
> It's not designed to tightly interweave
> docs and code (if it was designed for that, someone would have made a
> graphical full-screen literate debugger);
How do you know that?
> it's to allow detailed design to
> extend to any level of detail by allowing it to be expressed in an
> appropriate programming language.
>
> Certain chunks of a literate program -- let's call them the top chunks --
> contain the design of the program, in it most sweeping, abstract form.
> The reader is introduced to this design as such, in a way which will help
> him understand the design. The design is carried out into full detail.
>
>>> It's the opposite of literate programming -- it mixes design information
>>> into code. LP seperates them in a very convenient and automatically
>>> checkable way.
>
>> In what way is it automatically checkable?
>
> By running 'tangle' on it and compiling.
What does that check? Only that the code is all there and in the
right order. It doesn't check that the documentation matches the
code in any way; it doesn't check that the order of presentation
makes any sense; it doesn't check that the code does what it's
supposed to.
>> And what do you mean by "separated"?
>
> This is a 'top' chunk, a segment of the top-level design. And that, over
> at the end of the document or even in an appendix, is some elaboration of
> the design -- it happens to implement it. You don't have to understand
> the implementation in order to find the design; on the contrary, the
> design is presented to you seperately from the implementation.
I still don't understand your use of the word "separately". They
are not separated physically on the machine (they're side by side
in the same file). They are not separated physically in the printed
document (they're side by side on the same page). They are not
separated in the mind of the reader any more than they need be
with code in which comments are interleaved (given any literate
program in a decently expressive language, you can produce an
equivalent program not requiring any LP tools and containing
basically the same documentation and the same code in the same
order).
It's perfectly true that LP makes it much easier to arrange code
and documentation in a way that suits the documentation rather
than the exigencies of the compiler that will consume the code.
This is important. But to describe it in terms of "separation"
of code and documentation seems to me to be entirely misleading.
It's also true that LP allows you to separate some things that
would appear together in typical illiterate programs; for
instance, you can bring all the highest-level stuff together,
or all the error handling, and push bits of code+documentation
that would otherwise intervene into other parts of the program.
But this has nothing to do with separating code from documentation;
it's a matter of separating one bit of code from another bit that
doesn't belong next to it from any point of view other than the
compiler's.
> You seem to think I have a hangup with files.
I have no idea how you reach that conclusion. It hadn't occurred
to me that you might have a hangup with files.
> I don't; in fact, like you
> I would like it if everything I needed in life was in a single file,
> already opened in jed.
No, I wouldn't like that.
> Unlike you, I would rather have that single file be
> organized, so I never would have to search for what I needed next.
I too like things to be organised.
> ;-)
>
> The Author doesn't seem to care what I think, eh? :)
Am I supposed to understand that sentence?
--
Gareth McCaughan ················@pobox.com
sig under construction
On 08 Aug 1999 01:00:57 +0100, Gareth McCaughan wrote:
>William Tanksley wrote:
>>>> First because those comments are mixed with code, and they don't want to
>>>> read the code (it would be bad to do so).
>>> It would be bad not to do so.
>> It would be terrible to read code for which you have already designed a
>> replacement where the new design doesn't match the old.
>It wouldn't be terrible. At the very most it would be unnecessary.
At the worst it would be confusing and misleading, and result in time
wasted comprehending code which wouldn't have any affect on your code
because of the design change. I agree, though, that "terrible" is
hyperbole.
And that's a worst case, of course -- it assumes a significant design
change. But that's what I've been trying to discuss.
>>> I think this is a circular argument. "You shouldn't put this stuff
>>> in comments, you should put it in seoarate design docs. You should
>>> do this because no one will read the oomments, because all the stuff
>>> in them is also in the separate design docs". Hmmmm.
>> I spent quite a bit of time reading this, then examining your past posts.
>> I think I figured out our problem. I'm assuming the exisitance of a
>> design document; you're assuming the non-existance.
>No, I'm merely non-assuming its existence. :-)
:). To be more straightforward, I'm assuming its existance because if we
assume no separate documentation, comments are the only reasonable option.
>But even if there
>is a separate design document, I'm in favour of putting some
>design information in comments. Even if it's only "See the relevant
>section of the detailed design documentation for an explanation of
>why this code is the way it is".
I would indeed expect a single comment like this in each appplicable
function header. That's a good point. I also want interface
documentation in the header; it's helpful to the user and the programmer,
even if the design changes.
>> Once you've read and understood the document, you'll start working on the
>> code. You'll want to see in the code little tags which help you remember
>> which portion of the design you're looking at; this is what I recommend
>> comments for. The worst possible thing to see is either code which is
>> hard to read and doesn't appear to match the docs, or code with a comment
>> which contradicts the docs.
>Certainly.
>>>>> Neither have I :-) -- I was about to say "I didn't say `widely'",
>>>>> but then I took the precaution of checking my words and found that
>>>>> I had. I wonder what I meant.
>>>> I'm pretty sure you were making the point that documentation is
>>>> inconvenient when you're coding.
>>> I am absolutely certain that whatever I meant, it wasn't that.
>>> Documentation is essential when you are coding. I just like
>>> having the documentation and code more interleaved than you do.
>> Your idea of documentation is why so many people here dislike comments.
>I think this is descending into personal abuse here.
No, I'm sorry I gave that impression. My fault, my sloppy writing.
I meant to say, "many people here have expressed a dislike for all
comments because they saw too many comments used either as an echo of code
or instead of documentation."
>>>> Nothing in the code should talk about stuff that's not in the code. That
>>>> means no alternate algorithm comments. My exception is that if you write
>>>> really ugly code for the sake of speed, be sure to comment on why you
>>>> wrote ugly code, and include numbers which prove the effectiveness. That
>>>> way, when someone reads the code, they'll know what parts to not attempt
>>>> to understand.
>>> Right. So you agree with the example I gave earlier. Hooray! Now,
>>> why is this single case so extraordinary as to require completely
>>> opposite treatment from all others?
>> Because it involves obviously ugly code. The others involve design choices.
>I'm afraid I don't follow the logic here. Why does ugly code
>justify a comment, while other kinds of apparently-bad code don't?
A good engineer will look at ugly code, say, "It's broken," and be right
(its ugliness is a defect). The comment is there to prevent an engineer
from removing the apperent defect without noticing the actual defect the
ugliness is there to prevent (for example, performance).
Non-ugly code doesn't get an "alternate implementation" comment because a
good engineer won't change non-broken code. Even if a brilliant idea
occurs to him which would implement it even better. In other words, there
are only two types of "apparently-bad" code: broken code and ugly code.
Broken code is discovered by comparing to specs (including implicit ones),
so no need for comments; ugly code is visible immediately and so needs a
comment for protection.
In addition, it provides a disincentive to writing the ugly code in the
first place -- the programmer has to at least make up a plausible excuse :).
Writing "alternate design" comments won't change someone's mind if they
think they've got a better one -- your odds of thinking of all the
alternate designs are slim indeed :).
>>> To my mind, part of "understanding" a piece of code is understanding
>>> why it was written that way. I can do that much better if I have some
>>> idea of what went through the mind of the person who wrote it (or
>>> who designed it, if the tasks were split). So if I read something
>>> and have no idea why they didn't take some particular other approach
>>> that looks better at first sight, I don't really understand the code;
>>> just as I might not really understand some heavily-bummed incomprehensible
>>> maintenance nightmare of the kind you've just instanced. A little
>>> comment along the lines of "We could have done it this way, but
>>> it wouldn't have worked so well" would help.
>> If you read code and think about alternate designs, you need to be whacked
>> by the Angel of Design. Code isn't design; it's implementation.
>A piece of code is the implementation of a design. It contains both
>design and implementation. Dogmatic separation of the two is an error,
>arising from some people's tendency to confuse the two.
I don't understand.
Code is a concrete implementation of design. There are many possible
implementations of each design, and many possible designs. You can't
document them all, and you certainly don't want to try to document them
all in the code.
>> I remember a lab partner I had, who partway into the project was reading
>> my code and said, "why don't we do things a different way? This is
>> complicated!" Now, think about what he was saying. He had imagined a
>> clean, pure design, unsullied by code and all the special cases which
>> arise when coding. He was comparing this to several files full of code,
>> without attempting to really understand the design behind them.
>> His design was just as good, and I told him so. However, he was comparing
>> apples to applecores.
>I dare say he was. It's not clear to me what your point is.
He was thinking of brilliant new designs when he should have been coding.
The result was that he coded much slower, and resented me when I rightly
rejected his design change (the code was already half written), because he
saw the clean elegance of the design in his head and compared it to the
nitty-gritty implementation of the existing design.
A design in your head always looks prettier than a design once it's been
implemented. Experienced engineers learn that, and learn not to compare
designs and implementations aesthetically.
>>> No, you're missing the point. If I cut-and-paste some code that's
>>> known to do some particular task correctly, I DECREASE the risk of
>>> misimplementing that task. Certainly there's an increase in the
>>> risk of that task being subtly mismatched with what's actually
>>> needed, but to say that no risk decreases is simply wrong.
>> We're discussing redesign. If you cut'n'paste code belonging to a
>> different design, you WILL get cut'n'paste bugs. You WILL spend longer
>> fixing them than you would have writing new code.
>You're assuming there's a sharp distinction between reimplementation
>and redesign. There isn't. They're the same thing on different levels.
>The danger of disasters due to cut-and-paste increases as the level
>at which the change occurs gets higher; that's all.
That's partly true -- I'm sometimes assuming that. That's why I've tried
to put in phrases such as "consider doing this..." and "it is often
best...".
One of the statements I made which started this war was, "if you have to
rewrite some code due to redesign, seriously consider throwing away the
code and rewriting afresh."
That statement is a reasonable appeal.
Some of the things I've said are less carefully balanced -- but that's
because I'd like to prove my statements in the worst case as well as the
best ones.
>>> What do you mean by "the code and design are separated, but placed
>>> into the same document" that doesn't apply equally to code with
>>> design comments in it?
>> Code with design comments mingled is not seperated from the design
>> information. It's mingled.
>> LP code is seperated by the author into a full design presentation, down
>> to the lowest, most detailed level.
>I simply don't know what you mean by "separated" here.
Good. I don't either. But the author of the LP document does -- he
separates code into chunks. It's his call which part of the code goes
into which chunk.
If he believes that a given chunk of design should be separated by two
paragraphs from a chunk containing the code for that design, he can
enforce that separation. Two chapters? Also his choice.
[the purpose of LP:]
>> it's to allow detailed design to
>> extend to any level of detail by allowing it to be expressed in an
>> appropriate programming language.
>> Certain chunks of a literate program -- let's call them the top chunks --
>> contain the design of the program, in it most sweeping, abstract form.
>> The reader is introduced to this design as such, in a way which will help
>> him understand the design. The design is carried out into full detail.
>>>> It's the opposite of literate programming -- it mixes design information
>>>> into code. LP seperates them in a very convenient and automatically
>>>> checkable way.
>>> In what way is it automatically checkable?
>> By running 'tangle' on it and compiling.
>What does that check? Only that the code is all there and in the
>right order. It doesn't check that the documentation matches the
>code in any way; it doesn't check that the order of presentation
>makes any sense; it doesn't check that the code does what it's
>supposed to.
Of course. It only checks that the design information can be recombined
with the implementation information. Because that recombination is
automatic, it's possible to have an indefinite number of levels of design
detail, down to such a small level that even code is part of the design
document.
>>> And what do you mean by "separated"?
>> This is a 'top' chunk, a segment of the top-level design. And that, over
>> at the end of the document or even in an appendix, is some elaboration of
>> the design -- it happens to implement it. You don't have to understand
>> the implementation in order to find the design; on the contrary, the
>> design is presented to you seperately from the implementation.
>I still don't understand your use of the word "separately". They
>are not separated physically on the machine (they're side by side
>in the same file). They are not separated physically in the printed
>document (they're side by side on the same page).
Ah! A flash of inspiration strikes me!
I see the problem. You're assuming that "design" is certain English text
which accompanies/is related to a given chunk of code. Thus, you assume
that the design for any given LP "chunk" is contained entirely within the
TeX written directly above it.
Did I get that paraphrase right? If not, please resend that last packet ;).
One example of design which is separated from its implementation is the
following chunk:
<<handle interactive input>>=
<<read user input into this user's buffer>>
<<evaluate the user's input>>
<<print the result to user's console>>
@
You see? The design is unobscured by code.
>It's perfectly true that LP makes it much easier to arrange code
>and documentation in a way that suits the documentation rather
>than the exigencies of the compiler that will consume the code.
>This is important. But to describe it in terms of "separation"
>of code and documentation seems to me to be entirely misleading.
It's actually the main point, as I see it.
>It's also true that LP allows you to separate some things that
>would appear together in typical illiterate programs; for
>instance, you can bring all the highest-level stuff together,
>or all the error handling, and push bits of code+documentation
>that would otherwise intervene into other parts of the program.
>But this has nothing to do with separating code from documentation;
>it's a matter of separating one bit of code from another bit that
>doesn't belong next to it from any point of view other than the
>compiler's.
Actually, what LP is (definitely) supposed to do is convert the entire
program into documentation. There's no code/documentation dichotomy
because there's no code as such -- it's all design. Some of it's
high-level (such as the read-eval-print I put above), some of it's
low-level (such as a five-line chunk which outputs a char to the
terminal), but it's all design.
The text in literate programs (the stuff above the chunks) is free to act
as English documentation or as comments (in the traditional sense).
>Gareth McCaughan ················@pobox.com
--
-William "Billy" Tanksley
[I'm about to go away for a week and a half or so. If you want to
take this (marginally-relevant-to-the-group) discussion to e-mail
or something, that's fine with me.]
William Tanksley wrote:
>> But even if there
>> is a separate design document, I'm in favour of putting some
>> design information in comments. Even if it's only "See the relevant
>> section of the detailed design documentation for an explanation of
>> why this code is the way it is".
>
> I would indeed expect a single comment like this in each appplicable
> function header. That's a good point. I also want interface
> documentation in the header; it's helpful to the user and the programmer,
> even if the design changes.
Yes, definitely.
>> I'm afraid I don't follow the logic here. Why does ugly code
>> justify a comment, while other kinds of apparently-bad code don't?
>
> A good engineer will look at ugly code, say, "It's broken," and be right
> (its ugliness is a defect). The comment is there to prevent an engineer
> from removing the apperent defect without noticing the actual defect the
> ugliness is there to prevent (for example, performance).
>
> Non-ugly code doesn't get an "alternate implementation" comment because a
> good engineer won't change non-broken code. Even if a brilliant idea
> occurs to him which would implement it even better. In other words, there
> are only two types of "apparently-bad" code: broken code and ugly code.
> Broken code is discovered by comparing to specs (including implicit ones),
> so no need for comments; ugly code is visible immediately and so needs a
> comment for protection.
I remain baffled.
Suppose we have two pieces of code. Both perform to spec. The first
piece of code is terribly ugly: it's unclear and strange. Any decent
programmer[1] reading it will be disgusted by it. On the other hand,
after looking at it for a moment it becomes comprehensible. The second
piece of code is not, at first glance, ugly. It looks adequately clear.
But at second glance, any good enough programmer will see that it could
easily be rewritten to be somewhat clearer, much faster and much smaller.
[1] If you prefer the word "engineer", feel free to substitute it.
I'm saying "programmer" because it's the programming side of
the job that's relevant here.
According to you (unless I'm misunderstanding), the first piece of code
is *broken* (because it's ugly), even though it performs to spec,
whereas the second is not broken. That seems to me as if you're saying
that (provided there isn't an actual infringement of the formal
specifications) superficial qualities ("this code is ugly") matter
and deeper ones ("this code is terrible, even though it looks OK
at first") don't.
Ugliness is a defect, certainly. But I don't understand at all why
you say that ugliness and outright non-conformance are the only
two defects that are ever worth fixing.
> In addition, it provides a disincentive to writing the ugly code in the
> first place -- the programmer has to at least make up a plausible excuse :).
Certainly. Of course, it's also desirable to have a disincentive for
writing inefficient code, or code that (while not actually qualifying
for the word "ugly") isn't as clear as it coule be.
> Writing "alternate design" comments won't change someone's mind if they
> think they've got a better one -- your odds of thinking of all the
> alternate designs are slim indeed :).
I don't need to think of all the alternate designs. I need to think
of all the major design issues.
>>> If you read code and think about alternate designs, you need to be whacked
>>> by the Angel of Design. Code isn't design; it's implementation.
>
>> A piece of code is the implementation of a design. It contains both
>> design and implementation. Dogmatic separation of the two is an error,
>> arising from some people's tendency to confuse the two.
>
> I don't understand.
>
> Code is a concrete implementation of design. There are many possible
> implementations of each design, and many possible designs. You can't
> document them all, and you certainly don't want to try to document them
> all in the code.
Code is one level in a hierarchy of abstraction that has electrons
moving around circuits at one end and top-level design at the other.
Exactly what level the code is at depends on what sort of code it is,
how it's written, how clever the compiler that will process it is,
etc.
There isn't a sharp dichotomy between "implementation" and "design".
There's a continuum. The level at which code actually gets written
is determined by how much cleverer the people building the system are
than the compilers they use.
So it simply isn't true that reading code and thinking about alternate
designs is some sort of category mistake. Ideally, you'd read the code
and have a complete picture of the whole system (at all levels) in your
head, and be aware of all the issues that combined to make the code
the way it is. Unfortunately, for non-trivial systems we're a few
orders of magnitude too stupid to do that. But, given the wide variation
in how stupid different people are, I think it's a mistake to dogmatise
and say "You must never think about X while doing Y".
[naive lab partner story]
> He was thinking of brilliant new designs when he should have been coding.
> The result was that he coded much slower, and resented me when I rightly
> rejected his design change (the code was already half written), because he
> saw the clean elegance of the design in his head and compared it to the
> nitty-gritty implementation of the existing design.
>
> A design in your head always looks prettier than a design once it's been
> implemented. Experienced engineers learn that, and learn not to compare
> designs and implementations aesthetically.
Yes, I understood that that was the message of your story. What I
don't understand is its relevance to the discussion in hand. Perhaps
your point is that because your lab partner wasn't able to take into
account the discrepancy between his idea of how elegant his alternate
design would be and the reality of what it would really have been
like once translated into code, no one should try to think about
alternate designs while reading code; but surely you can't actually
believe such an absurd generalisation is sensible. So, what *is*
the relevance of the story?
>>> We're discussing redesign. If you cut'n'paste code belonging to a
>>> different design, you WILL get cut'n'paste bugs. You WILL spend longer
>>> fixing them than you would have writing new code.
>
>> You're assuming there's a sharp distinction between reimplementation
>> and redesign. There isn't. They're the same thing on different levels.
>> The danger of disasters due to cut-and-paste increases as the level
>> at which the change occurs gets higher; that's all.
>
> That's partly true -- I'm sometimes assuming that. That's why I've tried
> to put in phrases such as "consider doing this..." and "it is often
> best...".
>
> One of the statements I made which started this war was, "if you have to
> rewrite some code due to redesign, seriously consider throwing away the
> code and rewriting afresh."
>
> That statement is a reasonable appeal.
Certainly. I don't recall disagreeing with it.
> Some of the things I've said are less carefully balanced -- but that's
> because I'd like to prove my statements in the worst case as well as the
> best ones.
It's the "less carefully balanced" statements with which I'm taking
issue. So it seems to me, anyway.
>
>>>> What do you mean by "the code and design are separated, but placed
>>>> into the same document" that doesn't apply equally to code with
>>>> design comments in it?
>
>>> Code with design comments mingled is not seperated from the design
>>> information. It's mingled.
>
>>> LP code is seperated by the author into a full design presentation, down
>>> to the lowest, most detailed level.
>
>> I simply don't know what you mean by "separated" here.
>
> Good. I don't either. But the author of the LP document does -- he
> separates code into chunks. It's his call which part of the code goes
> into which chunk.
>
> If he believes that a given chunk of design should be separated by two
> paragraphs from a chunk containing the code for that design, he can
> enforce that separation. Two chapters? Also his choice.
Certainly, LP gives flexibility in deciding how to arrange your
code and documentation. That's hugely valuable. You appear to be
arguing that the merit of LP is simply that it forces code and
documentation to be separate. It doesn't do any such thing.
>>>>> It's the opposite of literate programming -- it mixes design information
>>>>> into code. LP seperates them in a very convenient and automatically
>>>>> checkable way.
>
>>>> In what way is it automatically checkable?
>
>>> By running 'tangle' on it and compiling.
>
>> What does that check? Only that the code is all there and in the
>> right order. It doesn't check that the documentation matches the
>> code in any way; it doesn't check that the order of presentation
>> makes any sense; it doesn't check that the code does what it's
>> supposed to.
>
> Of course. It only checks that the design information can be recombined
> with the implementation information. Because that recombination is
> automatic, it's possible to have an indefinite number of levels of design
> detail, down to such a small level that even code is part of the design
> document.
I still don't see what you mean by "checking".
I would say: By *not* separating code and documentation, but
combining them in a principled way, LP makes it easier to avoid
discrepancies between code and documentation -- because the code
itself is part of the documentation.
An LP system isn't "checking that the design information can be
recombined with the implementation information". It would be
nearer the mark (but still, I think, misleading) to say that
an LP system derives both from the same source, *forcing* them
to be (in a rather weak sense) consistent. That's a very different
business from "checking" that two genuinely separate documents
are consistent.
Note, though, that there can still be plenty of inconsistencies
in a literate program between code and documentation. Nothing
(other than my conscience) stops me writing
@ The following code is a crucial part of the garbage collector.
It decodes a record stored in the executable file describing
the contents of the registers, so that we know which registers
might contain pointers we need to follow.
@<Move the player to a new location in the ····@>=
{ int i,window_handle,product=0;
for (i=0; i<10; ++i) {
for (window_handle=0; window_handle<10; ++window_handle) {
product += i*window_handle*window_handle;
}
}
}
where I reckon there are four different levels, with serious
discrepancies between every pair.
>>>> And what do you mean by "separated"?
>
>>> This is a 'top' chunk, a segment of the top-level design. And that, over
>>> at the end of the document or even in an appendix, is some elaboration of
>>> the design -- it happens to implement it. You don't have to understand
>>> the implementation in order to find the design; on the contrary, the
>>> design is presented to you seperately from the implementation.
>
>> I still don't understand your use of the word "separately". They
>> are not separated physically on the machine (they're side by side
>> in the same file). They are not separated physically in the printed
>> document (they're side by side on the same page).
>
> Ah! A flash of inspiration strikes me!
>
> I see the problem. You're assuming that "design" is certain English text
> which accompanies/is related to a given chunk of code. Thus, you assume
> that the design for any given LP "chunk" is contained entirely within the
> TeX written directly above it.
I'm not assuming that that's what design is. I was assuming that
something like that is what you mean by "design", because that's
the message I got from your earlier articles. Maybe I misunderstood.
If by "design" you mean an abstract high-level description of the
intended structure of the system, not necessarily written down
anywhere (though it's helpful if it is), then I maintain that
it is not in our power to separate code from design. They are
separated by the fact of being at different levels of abstraction,
and nothing we can do will change that; they are united by the
fact that the code is an expression of the design (the actual
design, as opposed to the intended design I mentioned above),
and nothing we can do will change *that* either.
Now, if what you mean by "separating code from design" is "providing
a description of the design at an appropriate level, rather than
expecting people to read it out of the code", then of course I'm
all in favour of "separating code from design". And for this reason
I entirely agree with your liking for separate design documentation
for projects complicated enough to need it (which is most projects).
What I don't agree with is your contention that the code should be
presented in a way that ignores design.
I take it your argument goes like this. "We keep code out of design
documentation because when you're reading the design you shouldn't
need to bother about anything as low-level as the code; the aim is
to minimise the range of levels of abstraction you have to think at
simultaneously. For exactly the same reason, we should keep design
information out of code: someone reading the code should have their
mind unencumbered with irrelevant details of higher-level design."
The trouble with this argument is that it assumes, as you seem very
fond of assuming, a simple two-level dichotomy: there's code (low
level), and there's design (high level). But in reality there are
many, many levels of abstraction; the highest levels may be "pure
design", free of code, and the lowest levels conversely may be
"pure code", but in between it gets rather blurry. And the point is
that when reading something at one level, it's good to be aware of
the nearby levels. And, I claim, in the original example that
sparked off this whole discussion, the levels in question were
rather near.
> Did I get that paraphrase right? If not, please resend that last packet ;).
>
> One example of design which is separated from its implementation is the
> following chunk:
>
> <<handle interactive input>>=
> <<read user input into this user's buffer>>
> <<evaluate the user's input>>
> <<print the result to user's console>>
> @
>
> You see? The design is unobscured by code.
(defun handle-interactive-input ()
(let ((buffer (buffer-of current-user)))
(read-input-into-buffer buffer)
(display-evaluation-result
(evaluate-buffer-contents buffer))))
:-)
Of course, I agree that your sample chunk is a good example of
the way in which LP makes it possible to describe the structure
of a piece of software without bothering about details, while
ensuring that the details will be (to some degree) consistent
with the design. But I wouldn't call that separating design
from implementation. I'd call it combining design and implementation
in a positive way. That chunk *is* implementation, as well as
design. That's its strength.
The chunk happens to contain no code in whatever your substrate
language is. But it isn't free of code. It contains code in the
"noweb" macro language (I'm guessing that that's what it is). The
combination of the noweb macro language and the substrate language
is a nice high-level language, very good for writing comprehensible
programs; but it's still a language.
>> It's also true that LP allows you to separate some things that
>> would appear together in typical illiterate programs; for
>> instance, you can bring all the highest-level stuff together,
>> or all the error handling, and push bits of code+documentation
>> that would otherwise intervene into other parts of the program.
>> But this has nothing to do with separating code from documentation;
>> it's a matter of separating one bit of code from another bit that
>> doesn't belong next to it from any point of view other than the
>> compiler's.
>
> Actually, what LP is (definitely) supposed to do is convert the entire
> program into documentation. There's no code/documentation dichotomy
> because there's no code as such -- it's all design.
I wouldn't put it quite like that, but: Yes, exactly.
> Some of it's
> high-level (such as the read-eval-print I put above), some of it's
> low-level (such as a five-line chunk which outputs a char to the
> terminal), but it's all design.
And the code chunks themselves (like yours above) are *also* all code.
This is a good thing, not a bad thing.
> The text in literate programs (the stuff above the chunks) is free to act
> as English documentation or as comments (in the traditional sense).
Yes.
--
Gareth McCaughan ················@pobox.com
sig under construction
From: Friedrich Dominicus
Subject: Re: Comments, was Re: Parentheses Hierarchy
Date:
Message-ID: <37A68685.656D9B25@inka.de>
> XP is a wise practice. Thinking of design while you're coding means that
> you weren't thinking enough about design BEFORE YOU STARTED CODING. Sorry
> for yelling, I got excited ;-). Never, never, NEVER design while coding.
> If a single design change happens while you're coding, it's worth
> considering throwing away all your code and going back to design.
>
> I've done this, and not regretted it. I've also failed to do this, and
> regretted it very much.
I disagree completly. Programming is IMO neve a linear procedure. So if
I'm doing some programming and it than springs into my mind that there
might be a good design pattern I won't hesitate to grasp that and get it
shaped.
IMO nobody can be sure that design is finished before coding begins.
Regards
Friedrich
On Tue, 03 Aug 1999 08:04:53 +0200, Friedrich Dominicus wrote:
>> XP is a wise practice. Thinking of design while you're coding means that
>> you weren't thinking enough about design BEFORE YOU STARTED CODING. Sorry
>> for yelling, I got excited ;-). Never, never, NEVER design while coding.
>> If a single design change happens while you're coding, it's worth
>> considering throwing away all your code and going back to design.
>> I've done this, and not regretted it. I've also failed to do this, and
>> regretted it very much.
>I disagree completly. Programming is IMO neve a linear procedure. So if
>I'm doing some programming and it than springs into my mind that there
>might be a good design pattern I won't hesitate to grasp that and get it
>shaped.
>IMO nobody can be sure that design is finished before coding begins.
Of course not. That's why I recommended precisely what to do when such a
thing happens: you have two choices, keeping your old code and upgrading
it, or throwing your old code away and replacing it.
I recommend replacement. It's VERY tempting to keep the old code and try
to make it fit the new design, but the fact remains that the old code is
tied to the old design.
>Friedrich
--
-William "Billy" Tanksley
From: William Deakin
Subject: Re: Comments, was Re: Parentheses Hierarchy
Date:
Message-ID: <37A55B8B.3FBEC27D@pindar.com>
Gareth McCaughan wrote:
> William Tanksley wrote:
>
> >> Well, that's what I was arguing for. I thought you wanted comments
> >> of that sort separated from the code, and put in separate documentation.
> >
> > I do want those comments put in the docs, but I don't want the docs
> > _widely_ seperated from the code.
>
> I don't understand what this means.
Neither do I. If you want the design in with the code why not put the code and
the design document in the source control system. What about nice html tags. You
could then write the thing on emacs and read the design documentation at the
same time :-)
> >> ...When I'm reading a program, I want to understand what's going on and
> why.
These are the reasons why you have comments (baa) or documentation (raa).
> > I hope the programmer wasn't thinking about alternate designs while coding
> > -- that's a nightmare.
>
> Why is it a nightmare?
Yes why is it a nightmare?
> The programmer should be aware of possible changes that might have to be made
> to the code, so that he has the option of writing the code in such a way as to
> make those changes reasonably straightforward. (He might choose not to
> exercise that option; consider the slogan "You aren't going to need it" in
> so-called Extreme Programming.)
>
> > You, as the maintainer, shouldn't have to think about the alternates either
I think this is an argument about who makes the implementation design decisions.
There is the Systems Analyst is god or the Programmer is god models. I have
worked using both. This hinges around whether the programmer is give a high
level specification (design document) and is allowed to freedom to code as long
as stuff works to the interfaces and functions as specificed. Or whether the
programmer is a proxy who carries the design and implementation set down by the
SA.
> > None of that historical information ever gets seen if it was only placed
> > in the comments. The comments are dead before they can be used, and in
> > the way when they're not dead.
>
> Why are they "in the way"? Comments of the kind I'm thinking of
> go before the function, and they're usually only needed for
> relatively large functions. So it's not clear to me in what
> circumstances they'd be in the way.
Also if all of this is in source control and you can stop egrerious reformatting
of code ;-) a version diff will keep hold of what is going on with changes.
> >> I don't like having documentation and code separated by putting
> >> them in different documents. (Unless there's some tool that
> >> lets you link the two documents together flexibly, and navigate
> >> between them in the right way; that might be really good. I
> >> haven't seen such a tool.)
> >
> > That's true -- I really like the idea of Literate Programming.
>
> Me too, but it doesn't do what I was just describing. (Possibly an LP system
> could be devised that does; that would be nice.)
I suppose this is why I was talking about html tagged comments above. With emacs
running w3 and lisp-mode we could take over the world! using nothing more than
well documented CL code!
:-) will
From: William Deakin
Subject: Re: Comments, was Re: Parentheses Hierarchy
Date:
Message-ID: <37A16711.8976F2D1@pindar.com>
William Tanksley wrote:
> The boundary between design and detailed design does sometimes blur, but this
> one is clearly a design comment. Observe that it describes a step in an
> algorithm -- a "how", not a "what".
>
> Consider that any possible change to the code which that comment describes
> could not make the comment invalid without also making the algorithm
> invalid. Again, the itemization is also a useful clue.
I agree wholeheartedly with the statments above.
> I like the brief overview of the algorithm and data structure, as well as the
> mention of the design choices.
This seems to be conclusion Kernigan and Pike reach in their new book :-)
> (although I would say that the design choices belong in a seperate
> document; this code's getting deleted if the algorithm changes, and we
> don't want to risk making the maintainer think that cutting, pasting, and
> modifying your code will be sufficient because you've thought of it in
> advance).
Yes YES YESSSS
> But there's still another level of design, the detailed algorithm
> description. This is what line-by-line comments are good for.
Hmmmm. Why do you need these line by line comments?
> Another good use of line-by-line comments is justifying messy code -- "This
> loop structure was chosen because on the HP PA/RISC it takes 50 seconds to
> complete, while the much cleaner alternative (documented in so-and-so.tex)
> takes 100 seconds." That comment skirts the boundaries of
> implementation comments, but I would be VERY grateful to see it.
Surely this could be put somewhere else? Also why are you writing such
complicated code? If you want to substitute between two loop, why not write
them as seperate functions and put these kind of comments in the documentation
string?
Anyway this is not a 'what' rather a 'why'.
What about commenting data?
> Heh heh.
>
> (+ 5 (fubar)) ;; assemble "CALL FUBAR", then "ADD 5, %o0, %l0"
>
> Yup, I finally imagined an even WORSE comment than my original example :).
Joy. May your camels for ever be troubled by flatulence :-)~
:-) will
On Fri, 30 Jul 1999 09:49:21 +0100, William Deakin wrote:
>William Tanksley wrote:
>> But there's still another level of design, the detailed algorithm
>> description. This is what line-by-line comments are good for.
>Hmmmm. Why do you need these line by line comments?
Two major reasons. First of all, they allow the coder to implement the
algorithm correctly without having to glance back and forth at a spec
(this is a minor feature, easily accomplished by other means); and second,
it provides a means for people reading the code to get a detailed sense of
context.
Of course, I see that some people here are interpreting "line by line" to
mean "each and every line". No. :)
>> Another good use of line-by-line comments is justifying messy code -- "This
>> loop structure was chosen because on the HP PA/RISC it takes 50 seconds to
>> complete, while the much cleaner alternative (documented in so-and-so.tex)
>> takes 100 seconds." That comment skirts the boundaries of
>> implementation comments, but I would be VERY grateful to see it.
>Surely this could be put somewhere else? Also why are you writing such
>complicated code? If you want to substitute between two loop, why not write
>them as seperate functions and put these kind of comments in the documentation
>string?
The comment itself answers most of your questions -- I chose the
complicated form because the result ran unacceptably slow otherwise (oops,
the comment should have mentioned the criterion for acceptable speed).
The comment's there because that's the place the maintainer's going to be
looking at in horror and befuddlement. Putting a discussion of that in
the design document may be appropriate (if it's a design level decision),
but putting it here is far more important.
And for your last suggestion -- the ONLY excuse for writing this type of
comment is that you just wrote an evil function for the sake of justified
speed. You can't just do penance by also writing a pretty function; your
pretty function will never be executed because it's too SLOW. So all in
all, by writing a pretty function all you do is increase the size of the
app and waste some time.
>Anyway this is not a 'what' rather a 'why'.
Very good point.
>What about commenting data?
Data is a rapidly changing thing -- code is constant. I don't know how
I'd ever get the user to hold still long enough to let me comment his data.
>:-) will
--
-William "Billy" Tanksley
From: William Deakin
Subject: Re: Comments, was Re: Parentheses Hierarchy
Date:
Message-ID: <37A55116.7D981FBA@pindar.com>
William Tanksley wrote:
> >What about commenting data?
>
> Data is a rapidly changing thing -- code is constant. I don't know how I'd ever
> get the user to hold still long enough to let me comment his data.
What I mean by this was data structures, such as comments in a defstruct or
defclass explaining the use of each slot. Soz :-(
:-)~ will
From: William Deakin
Subject: Re: Comments, was Re: Parentheses Hierarchy
Date:
Message-ID: <37A160C1.E7102EB6@pindar.com>
My news reader and writer seems to be working! :-)
Gareth McCaughan wrote:
> > (+ i (next-freeble i)) ; add the result of next-freeble to i
> >
> > That's an implementation comment.
>
> Does anyone really write comments as uninformative as that?
Yes. Lots and lots of people do. For example (unfortunately I only have c++ to
hand :-( )
// Check class index of item.
if (ci < 0) {
ci = atoi(Item.m_CI);
}
if (newci < ci) { // Can never be less.
return false;
} else if (newci > ci) {
if (Item.m_ADTYPE == PageItemStr[cPageItems::ZCHD]) {
ci = newci;
} else { // Can only increase at a classification header.
return false;
}
}
There are hundreds, thousands or even millions of line of code like this.
> > Here's a design comment (shown without code, because it doesn't matter,
> > and because it's the same as the previous code):
> >
> > ; 3. Index to the next freeble in the zoof-list
> >
> > Note the itemization -- this is the third step in this algorithm (which
> > is, BTW, commonly used to determine what percent of all microfleems are
> > subradantiate).
Enough already. You have convinced me. I will restrict my irrational prejudice
to implementation comments. These are a neccessary evil but evil none the
less.
> My idea of a "design comment" would be something more like
>
> ;; The following function takes a greeble and returns the number
> ;; of free fleems with at most *FLEEM-LIMIT* degrees of freedom.
> ;; It does this by walking along the greeble's zoof-list looking
> ;; for freebles, and therefore takes time proportional to the
> ;; length of the zoof-list. If you have many subradiante micro-
> ;; -fleems, you may want to use hash tables instead; in this case
> ;; you'll need to change the definition of the GREEBLE class.
> ;; Alternatively, you could hide under your desk.
This is pretty damn sexy! If only any of the code I have ever worked on had
anything nearing this level of sense (or non-sense), I could see a point to
comments.
> I'm not saying "You've got the definition wrong, so there", since I've not
> heard the exact terms used before.
Neither had I, which is why I ask for clarification...
> But I think -- well, I hope -- that ";; add 1 to i" type comments are very
> rare, in which case it's more helpful to draw a distinction at a slightly
> higher level.
No, they are not. This is one of the reasons why I have a serious dislike of
(implementation) comments
:-) will
William Deakin wrote:
[someone else:]
>>> (+ i (next-freeble i)) ; add the result of next-freeble to i
>>>
>>> That's an implementation comment.
>>
>> Does anyone really write comments as uninformative as that?
>
> Yes. Lots and lots of people do. For example (unfortunately I only
> have c++ to hand :-( )
>
> // Check class index of item.
> if (ci < 0) {
> ci = atoi(Item.m_CI);
> }
>
> if (newci < ci) { // Can never be less.
> return false;
> } else if (newci > ci) {
> if (Item.m_ADTYPE == PageItemStr[cPageItems::ZCHD]) {
> ci = newci;
> } else { // Can only increase at a classification header.
> return false;
> }
> }
I think those comments are much better than the one I was horrified at.
They're still bad, of course, but they are at least relating what
happens to the semantics of what's going on, not just paraphrasing
one line of code into English in mechanical fashion.
> There are hundreds, thousands or even millions of line of code like this.
Those don't scare me, in the way that the first >>> line above does.
They're merely bad, not insane.
>> My idea of a "design comment" would be something more like
>>
>> ;; The following function takes a greeble and returns the number
>> ;; of free fleems with at most *FLEEM-LIMIT* degrees of freedom.
>> ;; It does this by walking along the greeble's zoof-list looking
>> ;; for freebles, and therefore takes time proportional to the
>> ;; length of the zoof-list. If you have many subradiante micro-
>> ;; -fleems, you may want to use hash tables instead; in this case
>> ;; you'll need to change the definition of the GREEBLE class.
>> ;; Alternatively, you could hide under your desk.
>
> This is pretty damn sexy! If only any of the code I have ever worked on had
> anything nearing this level of sense (or non-sense), I could see a point to
> comments.
I'm glad you liked it. Actually there are quite a lot of comments
of this sort in the code I write (except that most code doesn't
have many interesting implementation decisions of the kind whose
discussion occupies 3/4 of that comment). Plus, I'm afraid, a
fair number of one-liners whose purpose is to make skim-reading
the code easier. You might disapprove of those, since they don't
provide very much information that an intelligent reader couldn't
get from the raw code. But I find them helpful all the time.
--
Gareth McCaughan ················@pobox.com
sig under construction
From: Erik Naggum
Subject: Re: Comments, was Re: Parentheses Hierarchy
Date:
Message-ID: <3141842096510426@naggum.no>
* Samir Barjoud <·····@mindspring.com>
| The benefit, as I see it, of "READable" comments is that it would enable
| a programmer to work without files of source code. Comments are the only
| information (other than whitespace) lost upon READing. If comments were
| READable, than evaluating a bunch of definitions would be as good as
| saving them into a file.
consider a READ function that returns data useful to the Lisp system.
consider a READ function that returns data useful to an editor of Lisp
code. now, why would these two functions have to be the same? instead
of making comments part of the core Lisp representation, realize that
during the writing code, some of the time, the syntactic structure of the
code will be invalid. structure editors are a pain, pure and simple, and
if you had used them, you would know, but if you haven't used them, you
only see their good sides because the pain is non-obvious.
editing is task that is not well understood. look at Word, with billions
of dollars of research and development having gone into it, and it still
is a piece of crap. look at Emacs, with incredible amounts of time and
work having been poured into it by sometimes brilliant people, and we
still don't quite understand what helps people write fast and correctly,
and many serious mistakes are yet to be made, especially as people cling
to the stupid window-icon-mouse-pointer technology as if it were good in
itself.
representation-wise, however, there are some clearly advantageous lessons
to be learned from the editors of the past: (1) navigation is the single
most important property of a good editor. (2) aiding and abetting
authors with the nitty-gritty details without undue interference makes
them _really_ happy. (3) don't ever mess with the user's actual textual
formatting -- if the editor gets it wrong, user frustration reaches
record heights if the editor reverses the corrections. getting these
three issues right means we need to keep track of a lot of context and
information, and it just plain doesn't work to do it with simple-minded
data structures and semi-intelligent searching operations.
| Such a lisp system really seems appealing. To edit a function in such a
| system you would check it out (function definition printed from lisp
| memory to editor buffer), modify it, and check it back in again (evaluate
| it). Or you could check an entire package out. The system could also
| handle version control on its own. A dumped image could be considered a
| version control snapshot.
you know, the SGML people wanted exactly the same thing a few years ago,
and I'm not exaggerating when I say that users hate it. the single most
important reason users hate stuff like this that they aren't allowed to
break the rules at any time. and the reason for that is that if you let
them break the rules, you need to be very, very smart to manage to get
back in line. I don't think it's wise to ignore these issues from the
point of view of "structured" document editors. feel free to repeat
their experiment, however, but please see what they did and make sure
that you don't repeat mistakes of the past.
#:Erik
--
suppose we blasted all politicians into space.
would the SETI project find even one of them?
On Tue, 20 Jul 1999 10:38:11 -0400, joe comunale <·····@qcunix.qc.edu> wrote:
>Hi, I am an admirer of LISP... I only wish I knew it better. That
>being said, I would like (and dare) to suggest an improvement -
>introducing an idea we use in Physics. When an equation is too long,
>separate sets of parentheses are used in order to make the "sentence"
>more readable. The suggestion is to include these different sets as an
>integral part of the LISP interpreter with a standardized
>(customizable?) "hierarchy"
>
> The Parentheses "Hierarchy": < { [ ( ) ] } >
>
>I submit a sample comparison test below:
>
>(cond ( ( = 0 (mod n i) ) ( + i sum ) ) )
>
><cond { [ = 0 (mod n i) ] [ + i sum ] } >
>
>The "if-then" clauses are immediately recognizable. Whereas
>the "LISPy" statement leaves me scanning the line several
>times, and then having to check it again.
>
>I have been told how to do this using "set-macro-char," but this
>is an advanced feature which I can only imitate:
>
>(set-macro-character #\[ #'(lambda (stream char)
>(read-delimited-list #\] stream)))
>(set-macro-character #\] (get-macro-character #\)))
>
>My point is to set this up in the "kernel" and enable everyone,
>especially struggling students (like myself), to easily read LISP.
>In fact, the above definition may make the case for me. :)
I really think you need to use more than a toy example in order to
display the value of the "formalism;" it is not clear from a
pathologically simple (cond) form that this provides significant
benefit.
I'd rather display it thus:
(cond
((= 0 (mod n i))
(+ i sum)))
which, if rendered as you suggest, looks like:
<cond
{(= 0 [mod n i])
[+ i sum]}>
I don't see this being *substantially* different.
There are a couple of further concerns:
- You also need to modify the editor tools so that they treat these
'funny parens' as if they were parens.
- I don't think you want "squiggly brackets" {} on the same list as
"normal parentheses" (), as they are not visually different. (For a
not-Lisp-related matter, I often run into the problem with C code
that I have accidentally replaced a "{" with a "(", and couldn't see
the difference. Compilers quickly pick this up, but it's
*annoying.*)
There are Schemes that can can use [] as alternative parens; this
isn't a terrible idea, but I also suggest that it's not *incredibly*
valuable.
--
"I thought the idea with a language was that you didn't have to point
and grunt" - Chip Salzenberg
········@hex.net- <http://www.hex.net/~cbbrowne/langlisp.html>
Pierre R. Mai wrote: [1999-07-20 19:06 +0200]
[...]
> Just like in 99.9999% percent of all cases, the ground-breaking
> "improvements" on mathematical notation or definitions by students are
> bad ideas in the end
[...]
Compare to Feynman's story (in _Surely You're Joking, Mr. Feynman_,
a book *worth* reading) how he invented his own `new and improved'
mathematical notation---and abandoned it when he realised the
importance of communicating with others.
Vassil Nikolov
Permanent forwarding e-mail: ········@poboxes.com
For more: http://www.poboxes.com/vnikolov
Abaci lignei --- programmatici ferrei.
In article <·················@qcunix.qc.edu>, joe comunale <·····@qcunix.qc.edu> wrote:
> <cond { [ = 0 (mod n i) ] [ + i sum ] } >
Similar things have been proposed earlier. What do you
expect, Lisp is fourty years old. ;-)
One feature was that you could write something like:
(defun make-translation-designator (from to)
(assert (find (list from to) *translation-pairs* :test #'equalp)
(from to))
(concatenate 'string
(second (assoc from *babelfish-languages*))
"_"
(second (assoc to *babelfish-languages*]
And the last "]" closes all open parentheses.
joe comunale wrote:
> separate sets of
> parentheses
> are used in order to make the "sentence" more readable.
Parentheses? What parentheses? I haven't moticed any parentheses since
my first month of Lisp programming.
I like to ask people who complain about parentheses in lisp if they are
bothered by all the spaces between words in a newspaper. :)
As others have noted, the real problem is sticking everythin on one
line...i don't do that in /any/ language.
Glad you like Lisp! Don't worry, those ()s will disappear in about three
weeks. :) But do break your code into multiple lines!
cheers, ken
i apologize. i like my way. plus i use super-indentation.
; Q3 - return the sum of all prime numbers from 1 to n
(
defun
q3
(x)
(cond
(
(= x 2)
2
)
(
(isPrime x) (+ (q3 (- x 1)) x)
)
(
t
(q3 (- x 1))
)
)
)
..BWAHahahahaha... yes, yes... i'm MAd - MAD! I tell you... MAD MaAd
MAaaaad......
...(ahem) im ok now. :)
--
joe comunale
Queens College, NY
joe comunale wrote:
> Hi, I am an admirer of LISP... I only wish I knew it better. That being
> said,
> I would like (and dare) to suggest an improvement - introducing an idea
> we
> use in Physics. When an equation is too long, separate sets of
> parentheses
> are used in order to make the "sentence" more readable. The suggestion
> is
> to include these different sets as an integral part of the LISP
> interpreter with
> a standardized (customizable?) "hierarchy"
>
> The Parentheses "Hierarchy": < { [ ( ) ] } >
>
> I submit a sample comparison test below:
>
> (cond ( ( = 0 (mod n i) ) ( + i sum ) ) )
>
> <cond { [ = 0 (mod n i) ] [ + i sum ] } >
>
> In fact, the above definition may make the case for me. :)
>
* joe comunale <·····@qcunix.qc.edu>
| Hi, I am an admirer of LISP... I only wish I knew it better. That being
| said, I would like (and dare) to suggest an improvement - introducing an
| idea we use in Physics.
physics is a field very heavily optimized for those who understand it, or
to put it another way: it is not a field well known to treat beginners
nicely and many people are unable to grasp physics for a multitude of
reasons. you are therefore importing a trait from a beginner-hostile
world to another world that is not nice to you as a beginner simply
because you are _not_ a beginner in the former and are a beginner in the
latter. this is a ridiculously na�ve approach to solving problems.
| I submit a sample comparison test below:
|
| (cond ( ( = 0 (mod n i) ) ( + i sum ) ) )
Lisp programmers write (cond ((= 0 (mod n i)) (+ i sum))) and don't have
a problem with it, but if they do, they break it into two or three lines,
as several people have shown. moreover, modern-day programmers appear to
think color is the answer to all problems, so those who think this is
worth doing would colorize the condition differently from the consequent.
since you can add color without affecting the syntax, I would suggest you
investigate that option as a beginner rather than suggest changes that
could only affect future code, unless you were willing to make changes to
the way you view code. however, once you start down the road of making
modifications to how you view code, there's nothing to stop you from
making your proposed syntax change locally so that you see more diverse
parens, but the file contains normal parens.
I view it as a serious short-coming of programming textbooks that they
don't deal with issues of representation and presentation. it's integral
to Lisp whose lists have a linked list representation and a parenthesized
presentation, whose integers are sometimes made up of "bigits" but still
print like normal integers, and myriad other useful layerings of abstract
idea, machine representation, and presentation forms to the human. take
this Y2K silliness, which should be regarded as a monumental flaw in the
way people are taught how to deal with dates and time.
| My point is to set this up in the "kernel" and enable everyone,
| especially struggling students (like myself), to easily read LISP.
noble goal, but your suggestion is missing the boat -- students exposed
to your redesign would be at loss if you weren't also going to re-publish
all textbooks using your new system. I suggest you use colors as your
first approximation to ease readability, and if you can't do that, use a
paren matching mode that highlights the form the cursor/mouse is over,
and then resort to syntactic rewrites in the display to the user. and if
you aren't using Emacs, now is a good time to start. programming it is
even done in a sort of Lisp. (don't pick up too many habits, though.)
#:Erik
--
suppose we blasted all politicians into space.
would the SETI project find even one of them?
Erik Naggum <····@naggum.no> writes:
> however, once you start down the road of making modifications to
> how you view code, there's nothing to stop you from making your
> proposed syntax change locally so that you see more diverse
> parens, but the file contains normal parens.
>
> I view it as a serious short-coming of programming textbooks that
> they don't deal with issues of representation and presentation.
Once again Algol 60 is a significant advance to most of its
successors. I don't think the then current hardware could display the
bold face and the symbols in the printed representation but the
language definition clearly made the distinction.
--
Lieven Marchand <···@bewoner.dma.be>
If there are aliens, they play Go. -- Lasker