Parentheses Hierarchy
joe comunale
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
Lars Bjønnes
>(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
Pierre R. Mai
> 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 <pm...@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]
Tom Breton
> 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
Gareth McCaughan
[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 Gareth.M...@pobox.com
sig under construction
Christopher Browne
>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 -
>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"
>
>
>I submit a sample comparison test below:
>
>
><cond { [ = 0 (mod n i) ] [ + i sum ] } >
>
>the "LISPy" statement leaves me scanning the line several
>times, and then having to check it again.
>
>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 #\)))
>
>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
cbbr...@hex.net- <http://www.hex.net/~cbbrowne/langlisp.html>
Vassil Nikolov
[...]
> 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: vnik...@poboxes.com
For more: http://www.poboxes.com/vnikolov
Abaci lignei --- programmatici ferrei.
Rainer Joswig
> <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.
Samir Barjoud
> 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
sa...@mindspring.com
Tim Bradshaw
> 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
William Deakin
> 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
Mike McDonald
Samir Barjoud <sa...@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
mik...@mikemac.com
Tom Breton
> Tom Breton <t...@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
> In article <wkbtd65x...@mindspring.com>,
> Samir Barjoud <sa...@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.
Pierre R. Mai
> > `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?
Tim Bradshaw
> 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
Kent M Pitman
> mik...@mikemac.com (Mike McDonald) writes:
>
> > In article <wkbtd65x...@mindspring.com>,
> > Samir Barjoud <sa...@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.
William Deakin
> 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)
Mike McDonald
pm...@acm.org (Pierre R. Mai) writes:
> Tom Breton <t...@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
mik...@mikemac.com
David Thornley
William Deakin <w.de...@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.
>
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.
da...@thornley.net | If you don't, flee.
http://www.thornley.net/~thornley/david/ | O-
Kenny Tilton
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
Gareth McCaughan
> '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.
Tom Breton
> Tom Breton <t...@world.std.com> writes:
>
> > mik...@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.
Kent M Pitman
> > > 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.
William Deakin
> 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
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
Barry Margolin
Tom Breton <t...@world.std.com> wrote:
>Kent M Pitman <pit...@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, bar...@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.
Gareth McCaughan
[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.)
joe comunale
; 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 ] } >
>
Tom Breton
> Tom Breton <t...@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
> In article <m3emi0t...@world.std.com>,
> Tom Breton <t...@world.std.com> wrote:
> >Kent M Pitman <pit...@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.
Lars Marius Garshol
* 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.
Kent M Pitman
> 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.
Gareth McCaughan
> 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.
Erik Naggum
| 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?
Tom Breton
> Tom Breton <t...@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?
Erik Naggum
| 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.
Lieven Marchand
> 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 <m...@bewoner.dma.be>
If there are aliens, they play Go. -- Lasker
Vilhelm Sjöberg
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
Kent M Pitman
> Kent M Pitman <pit...@world.std.com> writes:
>
> > Tom Breton <t...@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.
Tom Breton
> Tom Breton <t...@world.std.com> writes:
>
> > Kent M Pitman <pit...@world.std.com> writes:
> >
> > > Tom Breton <t...@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
> On Sat, 24 Jul 1999 20:22:51 GMT, Tom Breton <t...@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.
Kent M Pitman
> 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.
Gareth McCaughan
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.
Tom Breton
> Tom Breton <t...@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.
Kent M Pitman
> Kent M Pitman wrote:
>
> > Tom Breton <t...@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
> ;;(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.
Erik Naggum
| 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 Naggum
| It could be an unreadable object.
we have #. to help us READ those.
Tim Bradshaw
> 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
Erik Naggum
| 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.
Lars Marius Garshol
* 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.
Tim Bradshaw
> 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
Lars Marius Garshol
* 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
* 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.
Erik Naggum
| Can processing instructions occur *anywhere* in SGML text?
no.
| In fact, can comments occur anywhere?
no.
#:Erik, who's trying to forget...
Pekka P. Pirinen
> 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.
>
> 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.
Kent M Pitman
> 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.
Kent M Pitman
> * Tim Bradshaw <t...@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.
Kent M Pitman
> * Gareth McCaughan <Gareth.M...@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.
Tom Breton
> * 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
> Gareth McCaughan <Gareth.M...@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
> Tom Breton <t...@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
>
> 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
> Tom Breton <t...@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
>
> 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
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.
Gareth McCaughan
[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.
Erik Naggum
| 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
Pierre R. Mai
> 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 <pm...@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]
Stig Hemmer
> 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.
Kent M Pitman
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.
William Tanksley
>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
Tom Breton
> 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 ...))
Vassil Nikolov
[...]
> 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: vnik...@poboxes.com
For more: http://www.poboxes.com/vnikolov
Abaci lignei --- programmatici ferrei.
w_de...@my-deja.com
> 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.
William Deakin
> 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
William 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?
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
Gareth McCaughan
>>> 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.
Vilhelm Sjöberg
wrote:
>, I realized that one major issue had never even
>come up:
Been there.
| From: Tim Bradshaw <t...@tfeb.org>
| Newsgroups: comp.lang.lisp
| Subject: Re: Comments, was Re: Parentheses Hierarchy
| Date: 21 Jul 1999 08:25:08 +0100
| Message-ID: <ey3673e...@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.
William 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?
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 Gareth.M...@pobox.com
--
-William "Billy" Tanksley
Gareth McCaughan
>>> (+ 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 */
William Deakin
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
> 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
William Deakin
> 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 Tanksley
>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.
Gareth McCaughan
> 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
[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.
William Tanksley
>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
>>>>> ; 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.
:-)
Rainer Joswig
> 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).
William Tanksley
>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
>> 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.)
William Deakin
> >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
William Deakin
> 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
Joerg-Cyril Hoehle
vil...@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
Gareth McCaughan <Gareth.M...@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 <lar...@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
Paolo Amoroso
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 <amo...@mclink.it>
Tim Bradshaw
> 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
Rainer Joswig
> 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.
William 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.
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.