I've found this to be the case in much of the code I've read.
Here are my theories on why:
1. Lisp programmers are too busy solving complex problems to document
their code.
2. Lisp is so powerful it makes programmers lazy, so why waste
keystrokes?
3. Lisp is more readable, so is more self-documenting.
4. With docstrings, who needs comments?
5. It's too hard to type in English after using s-expressions for so
long.
What do you all think? Any additions?
From: Thomas A. Russ
Subject: Re: Theories on why Lisp source *seems* to have less comments?
Date:
Message-ID: <ymiejwezgka.fsf@sevak.isi.edu>
"Jonathon McKitrick" <···········@bigfoot.com> writes:
> I've found this to be the case in much of the code I've read.
> Here are my theories on why:
...
> 3. Lisp is more readable, so is more self-documenting.
3a. There is more tendency to use long function and variable
names, which aids the self-documenting features of lisp.
...
6. The code tends to be shorter, so one can get an overview of the
function and understand the code directly for many cases.
7. Domain-specific languages are built which enable solving the
the problem at hand at a level that makes sense in the problem space
Probably another corallary of #3.
8. Most lisp code is experimental in nature, being developed using a
process I like to call exploratory programming. Comments aren't
written because programmer's don't know exactly what they are doing
yet, so commenting is premature until the program development is
complete. And then when it runs, someone ships it before the
programmers get a chance to add in the comments. ;)
--
Thomas A. Russ, USC/Information Sciences Institute
Thomas A. Russ wrote:
> 7. Domain-specific languages are built which enable solving the
> the problem at hand at a level that makes sense in the problem space
> Probably another corallary of #3.
I'd like to second this and add that in Common Lisp and other languages
with incrementally compiling environments, the overhead of adding new
data abstractions and new functions to decompose the problem space is
very minimal. Adding a new function or data abstraction in CL to
handle a subtask isn't any more difficult than finding a place for it
in the file, writing it and bam! you're done (even creating a new file
for it is low overhead). The overhead for adding a new class,
modifying a class's structure, or adding a new member function in
something like C++ (i.e., anything without an incrementally compiling
environment) is much, much higher. Adding a new file is even more
burdensome (updaing makefile, recompiling (perhaps a significant
portion of compilationally dependent files), relinking, etc can take a
long time). The larger the C++ project is, the more difficult it
becomes, whereas the size of the project in CL doesn't seem to be a
factor.
Of course, this is more due to the fact of the way CL & C++
environments work, rather than as a consequence of the languages
themselves. Imagining a CL development process similiar to the way the
GCC toolchain works would significantly detract from the fluid nature I
describe above. It's a shame, because C++ offers some interesting,
albeit clumsy, ways to write powerful abstractions to attack a problem
domain, it's just that the development cost of using them (in a
compiling & linking sense), especially in an experimental or
prototyping nature, is very high.
This relates to comments per the OP this way. In CL, it's so easy to
write very powerful abstractions that do exactly what they say they do
that comments are less necessary. Because the code is at a higher
level and closer to the problem domain, it's usually very clear what
the code is doing and how it contributes to dealing with the problem
domain. In C++, it's harder to work in the exploratory / prototyping
fashion that we have in CL, so once you start down a particular path in
C++, the cost of modifying or writing new abstractions, etc is very
high, so you usually stay with a half-baked set of abstractions that
may not match well with the problem. The code has to "work harder" to
solve the problem, thus the need for expository comments to explain the
impedence mismatch between the code's abstractions and the problem
domain are much more necessary.
Bottom line, you need less comments when you're writing in a domain
specific language than when you're not.
Glenn
From: lin8080
Subject: Re: Theories on why Lisp source *seems* to have less comments?
Date:
Message-ID: <44C1A7BD.8821826E@freenet.de>
"Thomas A. Russ" schrieb:
> 3a. There is more tendency to use long function and variable
> names, which aids the self-documenting features of lisp.
Something I will not miss. Especially in .de I can use the same
(...)names, but in German and no interpreter gets confusing about that.
This is often more useful than big comments. (ex: var-from-array3,
return-val-funct6). Yes and I make heavy use of copy&paste.
> 8. Most lisp code is experimental in nature, being developed using a
> process I like to call exploratory programming. Comments aren't
> written because programmer's don't know exactly what they are doing
> yet, so commenting is premature until the program development is
> complete. And then when it runs, someone ships it before the
> programmers get a chance to add in the comments. ;)
Thats in my case true.
Comment for me is the first line over a function. It acts more than a
"what to do here" than a text-info for other users. Next problem is, I
change the function often (to see what is that way or this way), so any
comment inside that function is time waste or after some changes no
longer true.
stefan
···@sevak.isi.edu (Thomas A. Russ) writes:
>
> 8. Most lisp code is experimental in nature, being developed using a
> process I like to call exploratory programming. Comments aren't
> written because programmer's don't know exactly what they are doing
> yet, so commenting is premature until the program development is
> complete. And then when it runs, someone ships it before the
> programmers get a chance to add in the comments. ;)
>
yeah, don't you hate that. You have geared yourself up for a couple of
days of extremely boring code commenting and before you get the
chance, the code gets shipped. Bummer ;-)
Tim
--
tcross (at) rapttech dot com dot au
Jonathon McKitrick wrote:
> What do you all think? Any additions?
I think it is because of functional part of lisp.
So your observation is actualy true not only for lisp but for all
functional languages.
Here's why.
In most cases comments inside the procedure describe state, i.e. why is
this peace of code is storing it's result to this particular local
variable, and how it is going to be used later.
In mostly functional code, the only description that is needed is
description of function itself, i.e. docstring. There's no need to
comment much inside the pure function.
Another need for comments is when you solve technical problem, not
related to function itself.
For example quicksort. C quicksort example is not that much of a
quicksort, rather than a joggling with local variables with intent to
preserve as much memory as possible.
"Jonathon McKitrick" <···········@bigfoot.com> writes:
> I've found this to be the case in much of the code I've read.
> Here are my theories on why:
>
> 1. Lisp programmers are too busy solving complex problems to document
> their code.
> 2. Lisp is so powerful it makes programmers lazy, so why waste
> keystrokes?
> 3. Lisp is more readable, so is more self-documenting.
> 4. With docstrings, who needs comments?
> 5. It's too hard to type in English after using s-expressions for so
> long.
>
> What do you all think? Any additions?
Bottom-up development may be a reason too.
It feels like writing a math equation.
You don't write comments inside math equations.
But you may surround your theorems with some comments.
--
__Pascal Bourguignon__ http://www.informatimago.com/
PLEASE NOTE: Some quantum physics theories suggest that when the
consumer is not directly observing this product, it may cease to
exist or will exist only in a vague and undetermined state.
From: Pascal Costanza
Subject: Re: Theories on why Lisp source *seems* to have less comments?
Date:
Message-ID: <4id5kkF38hedU1@individual.net>
Jonathon McKitrick wrote:
> I've found this to be the case in much of the code I've read.
> Here are my theories on why:
>
> 1. Lisp programmers are too busy solving complex problems to document
> their code.
> 2. Lisp is so powerful it makes programmers lazy, so why waste
> keystrokes?
> 3. Lisp is more readable, so is more self-documenting.
> 4. With docstrings, who needs comments?
> 5. It's too hard to type in English after using s-expressions for so
> long.
>
> What do you all think? Any additions?
The value of comments is very questionable. It's very likely that
comments and code are out of sync because you rarely do both change code
and update the comments to reflect the changes. There is no tool that
could check whether your comments are still "correct". Comments that are
out of sync are potentially more harmful than having no comments.
This is actually one of the rationales behind one of the Extreme
Programming practices, which is not to comment code. Here are more
explanations from the XP crowd:
- If code is so complicated that you need to comment it for increasing
its understandability, it's probably a better idea to rewrite and
simplify it.
- It's better to spend your time on writing test suites, which are
actually executable "comments": they illustrate how your code is
supposed to be used, and they give you the benefit of showing you what
breaks and doesn't break when you make changes to your code. Most of the
time, it's actually quite straightforward to formulate your assumptions,
requirements, bug reports, etc., as test cases.
- It's also relatively straightforward to add assertions and checks to
your code that you can switch on (during development) and off (for
deployment). This is actually a light-weight form of "design by
contract", and also has the effect that you have "executable comments"
in your code.
In the case of Lisp I would add that its facilities for functional and
syntactic (macro) abstractions give you more possibilities to write
"self-documenting" code, i.e., code that declares its intentions instead
of spelling out each and every step of its execution.
Pascal
--
My website: http://p-cos.net
Closer to MOP & ContextL:
http://common-lisp.net/project/closer/
Pascal Costanza wrote:
> Jonathon McKitrick wrote:
> > I've found this to be the case in much of the code I've read.
> > Here are my theories on why:
> >
> > 1. Lisp programmers are too busy solving complex problems to document
> > their code.
> > 2. Lisp is so powerful it makes programmers lazy, so why waste
> > keystrokes?
> > 3. Lisp is more readable, so is more self-documenting.
> > 4. With docstrings, who needs comments?
> > 5. It's too hard to type in English after using s-expressions for so
> > long.
> >
> > What do you all think? Any additions?
>
> The value of comments is very questionable. It's very likely that
> comments and code are out of sync because you rarely do both change code
> and update the comments to reflect the changes. There is no tool that
> could check whether your comments are still "correct". Comments that are
> out of sync are potentially more harmful than having no comments.
>
> This is actually one of the rationales behind one of the Extreme
> Programming practices, which is not to comment code. Here are more
> explanations from the XP crowd:
I've been hearing this a lot recently. Some of it seems to be sensible
and some fairly nuts to me.
> - If code is so complicated that you need to comment it for increasing
> its understandability, it's probably a better idea to rewrite and
> simplify it.
Yes, if you can simplify it. Some things are just complicated.
> - It's better to spend your time on writing test suites, which are
> actually executable "comments": they illustrate how your code is
> supposed to be used, and they give you the benefit of showing you what
> breaks and doesn't break when you make changes to your code. Most of the
> time, it's actually quite straightforward to formulate your assumptions,
> requirements, bug reports, etc., as test cases.
IMHO This idea is really evil. Comments get out of date even though
their right next to the code in question. Unit test however are
normally in a totally different file, this gives them even less chance
of staying in date. It also makes things much more difficult for the
first time reader, a very important audience for comments.
> - It's also relatively straightforward to add assertions and checks to
> your code that you can switch on (during development) and off (for
> deployment). This is actually a light-weight form of "design by
> contract", and also has the effect that you have "executable comments"
> in your code.
This however is an excellent idea.
> In the case of Lisp I would add that its facilities for functional and
> syntactic (macro) abstractions give you more possibilities to write
> "self-documenting" code, i.e., code that declares its intentions instead
> of spelling out each and every step of its execution.
Yes.
Another important difference compared to C and C++ is wierdness.
Many of my comments in C code say something like "this library function
does something slightly unexpected", or make some remark about header
namespaces or the semantics of something with innocent syntax. Lisp
has less wierdness that shows up often.
Rob Thorpe wrote:
> Pascal Costanza wrote:
*snip*
> > - It's better to spend your time on writing test suites, which are
> > actually executable "comments": they illustrate how your code is
> > supposed to be used, and they give you the benefit of showing you what
> > breaks and doesn't break when you make changes to your code. Most of the
> > time, it's actually quite straightforward to formulate your assumptions,
> > requirements, bug reports, etc., as test cases.
>
> IMHO This idea is really evil. Comments get out of date even though
> their right next to the code in question. Unit test however are
> normally in a totally different file, this gives them even less chance
> of staying in date.
Not really. Unlike comments, automated tools can check to ensure that
unit tests are in line with what the code does. When tests fail, you
know they're no longer accurate examples of possible uses of the code.
*snip*
"Rob Thorpe" <·············@antenova.com> writes:
>> - It's better to spend your time on writing test suites, which are
>> actually executable "comments": they illustrate how your code is
>> supposed to be used, and they give you the benefit of showing you what
>> breaks and doesn't break when you make changes to your code. Most of the
>> time, it's actually quite straightforward to formulate your assumptions,
>> requirements, bug reports, etc., as test cases.
>
> IMHO This idea is really evil. Comments get out of date even though
> their right next to the code in question. Unit test however are
> normally in a totally different file, this gives them even less chance
> of staying in date.
Of course not. The big difference, is that everytime you recompile
your sources, you run the unit test too. As Pascal said, there's no
automatic way to check the comments, unless you write them under the
form of ASSERT, DECLARE or other syntactic abstraction (in which case
they're not comment anymore).
> It also makes things much more difficult for the
> first time reader, a very important audience for comments.
--
__Pascal Bourguignon__ http://www.informatimago.com/
You never feed me.
Perhaps I'll sleep on your face.
That will sure show you.
Pascal Bourguignon wrote:
> "Rob Thorpe" <·············@antenova.com> writes:
>
> >> - It's better to spend your time on writing test suites, which are
> >> actually executable "comments": they illustrate how your code is
> >> supposed to be used, and they give you the benefit of showing you what
> >> breaks and doesn't break when you make changes to your code. Most of the
> >> time, it's actually quite straightforward to formulate your assumptions,
> >> requirements, bug reports, etc., as test cases.
> >
> > IMHO This idea is really evil. Comments get out of date even though
> > their right next to the code in question. Unit test however are
> > normally in a totally different file, this gives them even less chance
> > of staying in date.
>
> Of course not. The big difference, is that everytime you recompile
> your sources, you run the unit test too. As Pascal said, there's no
> automatic way to check the comments, unless you write them under the
> form of ASSERT, DECLARE or other syntactic abstraction (in which case
> they're not comment anymore).
It's often very simple to modify a piece of code to perform a new
function and get it right.
If the tests aren't updated at this point then they will still pass,
but they will not document the new functionality.
> > It also makes things much more difficult for the
> > first time reader, a very important audience for comments.
What about this point? How on earth in the reader supposed to
understand the code.
If I were given a piece of source without comments I would refuse to
work on it.
Rob Thorpe wrote:
> Pascal Bourguignon wrote:
> > "Rob Thorpe" <·············@antenova.com> writes:
> >
> > >> - It's better to spend your time on writing test suites, which are
> > >> actually executable "comments": they illustrate how your code is
> > >> supposed to be used, and they give you the benefit of showing you what
> > >> breaks and doesn't break when you make changes to your code. Most of the
> > >> time, it's actually quite straightforward to formulate your assumptions,
> > >> requirements, bug reports, etc., as test cases.
> > >
> > > IMHO This idea is really evil. Comments get out of date even though
> > > their right next to the code in question. Unit test however are
> > > normally in a totally different file, this gives them even less chance
> > > of staying in date.
> >
> > Of course not. The big difference, is that everytime you recompile
> > your sources, you run the unit test too. As Pascal said, there's no
> > automatic way to check the comments, unless you write them under the
> > form of ASSERT, DECLARE or other syntactic abstraction (in which case
> > they're not comment anymore).
>
> It's often very simple to modify a piece of code to perform a new
> function and get it right.
> If the tests aren't updated at this point then they will still pass,
> but they will not document the new functionality.
I think you're missing the point. There are reasons why this isn't a
problem:
1. You should write the tests for the new functionality before you
write the new functionality itself. Therefore, the tests always cover
all expected functionality.
2. The purported advantage of tests isn't that they document all
possible aspects of the code, anyway. The advantage tests have over
comments is that if they're wrong, you always know. Even if a test is
out of date, if it passes you know _that test_ is valid code, so it's
still useful.
> > > It also makes things much more difficult for the
> > > first time reader, a very important audience for comments.
>
> What about this point? How on earth in the reader supposed to
> understand the code.
> If I were given a piece of source without comments I would refuse to
> work on it.
From: Patrick May
Subject: Re: Theories on why Lisp source *seems* to have less comments?
Date:
Message-ID: <m2lkqm5f54.fsf@Dagney.local>
"Rob Thorpe" <·············@antenova.com> writes:
> Pascal Bourguignon wrote:
> > Of course not. The big difference, is that everytime you
> > recompile your sources, you run the unit test too. As Pascal
> > said, there's no automatic way to check the comments, unless you
> > write them under the form of ASSERT, DECLARE or other syntactic
> > abstraction (in which case they're not comment anymore).
>
> It's often very simple to modify a piece of code to perform a new
> function and get it right.
> If the tests aren't updated at this point then they will still pass,
> but they will not document the new functionality.
That's exactly why one of the XP practices is test-driven
development. The test is written first. No code is written except to
make a failing test pass.
Regards,
Patrick
------------------------------------------------------------------------
S P Engineering, Inc. | The experts in large scale distributed OO
| systems design and implementation.
···@spe.com | (C++, Java, Common Lisp, Jini, middleware, SOA)
Patrick May wrote:
> "Rob Thorpe" <·············@antenova.com> writes:
> > Pascal Bourguignon wrote:
> > > Of course not. The big difference, is that everytime you
> > > recompile your sources, you run the unit test too. As Pascal
> > > said, there's no automatic way to check the comments, unless you
> > > write them under the form of ASSERT, DECLARE or other syntactic
> > > abstraction (in which case they're not comment anymore).
> >
> > It's often very simple to modify a piece of code to perform a new
> > function and get it right.
> > If the tests aren't updated at this point then they will still pass,
> > but they will not document the new functionality.
>
> That's exactly why one of the XP practices is test-driven
> development. The test is written first. No code is written except to
> make a failing test pass.
I think maintainance programmers are much less likely to abide by that
instruction than the are to abide by a request to document their code.
"Rob Thorpe" <·············@antenova.com> writes:
> Patrick May wrote:
>> "Rob Thorpe" <·············@antenova.com> writes:
>> > Pascal Bourguignon wrote:
>> > > Of course not. The big difference, is that everytime you
>> > > recompile your sources, you run the unit test too. As Pascal
>> > > said, there's no automatic way to check the comments, unless you
>> > > write them under the form of ASSERT, DECLARE or other syntactic
>> > > abstraction (in which case they're not comment anymore).
>> >
>> > It's often very simple to modify a piece of code to perform a new
>> > function and get it right.
>> > If the tests aren't updated at this point then they will still pass,
>> > but they will not document the new functionality.
>>
>> That's exactly why one of the XP practices is test-driven
>> development. The test is written first. No code is written except to
>> make a failing test pass.
>
> I think maintainance programmers are much less likely to abide by that
> instruction than the are to abide by a request to document their code.
>
That depends on whether the original code was developed using unit
testing. If it was, continuing the same model of development for
maintenance programmers has enough benefits to convince them regarding
the value of the methodology.
For those who still won't do it, two choices really - resign or be
fired.
If the software wasn't developed using unit testing, the overhead of
maintenance programmers creating unit tests for the whole system is
unlikely to be practicle.
Tim
In article <1153550169.382225.64210
@i3g2000cwc.googlegroups.com>, ·············@antenova.com
says...
> > That's exactly why one of the XP practices is test-driven
> > development. The test is written first. No code is written except to
> > make a failing test pass.
>
> I think maintainance programmers are much less likely to abide by that
> instruction than the are to abide by a request to document their code.
>
If "write the test first" rule quarantees something, then I
think that "write the comment first" rule is not any worse.
Comments have important advantage: they can explain _why_
particular algorithm works, while reading code only explain
_how_ it works. It is big difference.
From: Kent M Pitman
Subject: Re: Theories on why Lisp source *seems* to have less comments?
Date:
Message-ID: <uodvhng4z.fsf@nhplace.com>
Majorinc, Kazimir <·······@false.email> writes:
> In article <1153550169.382225.64210
> @i3g2000cwc.googlegroups.com>, ·············@antenova.com
> says...
> > > That's exactly why one of the XP practices is test-driven
> > > development. The test is written first. No code is written except to
> > > make a failing test pass.
> >
> > I think maintainance programmers are much less likely to abide by that
> > instruction than the are to abide by a request to document their code.
> >
>
> If "write the test first" rule quarantees something, then I
> think that "write the comment first" rule is not any worse.
>
> Comments have important advantage: they can explain _why_
> particular algorithm works, while reading code only explain
> _how_ it works. It is big difference.
Actually, comments have the problem that they increase inertia in a
program. They're good for very stable programs, but they get out of
date easily. Program text itself does not get out of date. So making
sure the language itself (both in semantics and good style rules)
contains the elements for saying what you want to say, so that you
don't need to resort to comments, is certainly one of the things that
makes Lisp programs use fewer comments. Lisp programs, being
dynamically changeable, change a lot--at least in my experience.
Rather than rewrite comments, I just code the assumptions into the
programs where I can. So if you do that, comment and code are
concurrent, not one ahead of the other.
"Rob Thorpe" <·············@antenova.com> writes:
>> > It also makes things much more difficult for the
>> > first time reader, a very important audience for comments.
>
> What about this point? How on earth in the reader supposed to
> understand the code.
> If I were given a piece of source without comments I would refuse to
> work on it.
If you need a translator you shouldn't be allowed to touch the code!
--
__Pascal Bourguignon__ http://www.informatimago.com/
ADVISORY: There is an extremely small but nonzero chance that,
through a process known as "tunneling," this product may
spontaneously disappear from its present location and reappear at
any random place in the universe, including your neighbor's
domicile. The manufacturer will not be responsible for any damages
or inconveniences that may result.
Pascal Bourguignon wrote:
> "Rob Thorpe" <·············@antenova.com> writes:
> >> > It also makes things much more difficult for the
> >> > first time reader, a very important audience for comments.
> >
> > What about this point? How on earth in the reader supposed to
> > understand the code.
> > If I were given a piece of source without comments I would refuse to
> > work on it.
>
> If you need a translator you shouldn't be allowed to touch the code!
I can understand any working code if I need to by emulating manually
the process of the compiler. However I don't wish to do that, it's
incredibly time consuming and prone to error. As a result I don't wish
to work on code without comments, I have better things to do with my
life.
As Abelson & Sussman said "Programs must be written for people to read,
and only incidentally for machines to execute." A program written
without comments is almost always going to be one written only for a
machine to execute, because so many of the subtleties of a program
can't be relayed in code, even Lisp code.
"Rob Thorpe" <·············@antenova.com> writes:
> Pascal Bourguignon wrote:
>> "Rob Thorpe" <·············@antenova.com> writes:
>> >> > It also makes things much more difficult for the
>> >> > first time reader, a very important audience for comments.
>> >
>> > What about this point? How on earth in the reader supposed to
>> > understand the code.
>> > If I were given a piece of source without comments I would refuse to
>> > work on it.
>>
>> If you need a translator you shouldn't be allowed to touch the code!
>
> I can understand any working code if I need to by emulating manually
> the process of the compiler. However I don't wish to do that, it's
> incredibly time consuming and prone to error. As a result I don't wish
> to work on code without comments, I have better things to do with my
> life.
>
> As Abelson & Sussman said "Programs must be written for people to read,
> and only incidentally for machines to execute." A program written
> without comments is almost always going to be one written only for a
> machine to execute, because so many of the subtleties of a program
> can't be relayed in code, even Lisp code.
I stand on my case. If you need comments because you have something
better to do than program, by all mean please resign and go do your
better things.
--
__Pascal Bourguignon__ http://www.informatimago.com/
"Logiciels libres : nourris au code source sans farine animale."
Pascal Bourguignon wrote:
> "Rob Thorpe" <·············@antenova.com> writes:
>
> > Pascal Bourguignon wrote:
> >> "Rob Thorpe" <·············@antenova.com> writes:
> >> >> > It also makes things much more difficult for the
> >> >> > first time reader, a very important audience for comments.
> >> >
> >> > What about this point? How on earth in the reader supposed to
> >> > understand the code.
> >> > If I were given a piece of source without comments I would refuse to
> >> > work on it.
> >>
> >> If you need a translator you shouldn't be allowed to touch the code!
> >
> > I can understand any working code if I need to by emulating manually
> > the process of the compiler. However I don't wish to do that, it's
> > incredibly time consuming and prone to error. As a result I don't wish
> > to work on code without comments, I have better things to do with my
> > life.
> >
> > As Abelson & Sussman said "Programs must be written for people to read,
> > and only incidentally for machines to execute." A program written
> > without comments is almost always going to be one written only for a
> > machine to execute, because so many of the subtleties of a program
> > can't be relayed in code, even Lisp code.
>
> I stand on my case. If you need comments because you have something
> better to do than program, by all mean please resign and go do your
> better things.
Well I often do have better things to do than programming, but that's
also beside the point.
What I said was I have better things to do than try to understand
programs by emulating the action of a computer, when there are much
simpler ways to understand them. Like explaining them in English!
"Rob Thorpe" <·············@antenova.com> writes:
> Pascal Bourguignon wrote:
>> "Rob Thorpe" <·············@antenova.com> writes:
>>
>> > Pascal Bourguignon wrote:
>> >> "Rob Thorpe" <·············@antenova.com> writes:
>> >> >> > It also makes things much more difficult for the
>> >> >> > first time reader, a very important audience for comments.
>> >> >
>> >> > What about this point? How on earth in the reader supposed to
>> >> > understand the code.
>> >> > If I were given a piece of source without comments I would refuse to
>> >> > work on it.
>> >>
>> >> If you need a translator you shouldn't be allowed to touch the code!
>> >
>> > I can understand any working code if I need to by emulating manually
>> > the process of the compiler. However I don't wish to do that, it's
>> > incredibly time consuming and prone to error. As a result I don't wish
>> > to work on code without comments, I have better things to do with my
>> > life.
>> >
>> > As Abelson & Sussman said "Programs must be written for people to read,
>> > and only incidentally for machines to execute." A program written
>> > without comments is almost always going to be one written only for a
>> > machine to execute, because so many of the subtleties of a program
>> > can't be relayed in code, even Lisp code.
>>
>> I stand on my case. If you need comments because you have something
>> better to do than program, by all mean please resign and go do your
>> better things.
>
> Well I often do have better things to do than programming, but that's
> also beside the point.
>
> What I said was I have better things to do than try to understand
> programs by emulating the action of a computer, when there are much
> simpler ways to understand them. Like explaining them in English!
That said, my understanding of what Abelson & Sussman said is not that
the program code should be commented, but that it should be
understandable. It's an anti-obfuscation stance, not a pro-comment one.
--
__Pascal Bourguignon__ http://www.informatimago.com/
From: Holger Schauer
Subject: Re: Theories on why Lisp source *seems* to have less comments?
Date:
Message-ID: <yxzejwa9h10.fsf@gmx.de>
On 4709 September 1993, Pascal Bourguignon wrote:
> That said, my understanding of what Abelson & Sussman said is not that
> the program code should be commented, but that it should be
> understandable. It's an anti-obfuscation stance, not a pro-comment one.
More often than not, comments (should) explain why the code looks so
obfuscated.
Holger
--
--- http://www.coling.uni-freiburg.de/~schauer/ ---
Fachbegriffe der Informatik - Einfach erkl�rt
81: Cursor-Tasten
Neumodischer Schnickschnack. (Gert D�ring)
From: David Steuber
Subject: Re: Theories on why Lisp source *seems* to have less comments?
Date:
Message-ID: <87zmey89wq.fsf@david-steuber.com>
"Rob Thorpe" <·············@antenova.com> writes:
> If I were given a piece of source without comments I would refuse to
> work on it.
This would severely limit the code you would work on. I find that
well commented (or commented at all) code is the exception and not the
rule. Also, keeping comments in sync with the code is a pita when the
code is not fully formed yet. It is much better to choose appropriate
names for functions and variables to reflect their intention.
--
The lithobraker. Zero distance stops at any speed.
This post uses 100% post consumer electrons and 100% virgin photons.
At 2.6 miles per minute, you don't really have time to get bored.
--- Pete Roehling on rec.motorcycles
From: Ken Tilton
Subject: Re: Theories on why Lisp source *seems* to have less comments?
Date:
Message-ID: <%Wkxg.621$md7.386@fe09.lga>
David Steuber wrote:
> "Rob Thorpe" <·············@antenova.com> writes:
>
>
>>If I were given a piece of source without comments I would refuse to
>>work on it.
>
>
> This would severely limit the code you would work on. I find that
> well commented (or commented at all) code is the exception and not the
> rule. Also, keeping comments in sync with the code is a pita when the
> code is not fully formed yet. It is much better to choose appropriate
> names for functions and variables to reflect their intention.
>
Let's not forget how badly people write. This is the same reason that
the only doc that interests me is working examples.
ken
--
Cells: http://common-lisp.net/project/cells/
"I'll say I'm losing my grip, and it feels terrific."
-- Smiling husband to scowling wife, New Yorker cartoon
Ken Tilton <·········@gmail.com> writes:
> David Steuber wrote:
>> "Rob Thorpe" <·············@antenova.com> writes:
>>
>>
>>>If I were given a piece of source without comments I would refuse to
>>>work on it.
>>
>>
>> This would severely limit the code you would work on. I find that
>> well commented (or commented at all) code is the exception and not the
>> rule. Also, keeping comments in sync with the code is a pita when the
>> code is not fully formed yet. It is much better to choose appropriate
>> names for functions and variables to reflect their intention.
>>
>
> Let's not forget how badly people write. This is the same reason that
> the only doc that interests me is working examples.
>
I wonder if that's why Knuth's Literate Programming has never really
taken off. Knuth's perspective was that we need to be able to write
well in order to write good software. this might be true, but most
people don't write very well - which also probably explains why so
much software is so poorly written. If you can't express ideas clearly
in your native language, I guess you are unlikely to do it well in an
intermediate language designed to be readable by humans and
interpreted by machines.
Tim
--
tcross (at) rapttech dot com dot au
On 2006-07-25 08:05:31 -0400, Tim X <····@nospam.dev.null> said:
> If you can't express ideas clearly
> in your native language, I guess you are unlikely to do it well in an
> intermediate language designed to be readable by humans and
> interpreted by machines.
Hear, hear. There is a wave of people who think that because they work
in technical fields they don't need to be skilled in written
communication. The ability to write well has always been prized because
it is one of the few truly excellent indicators we have of how well a
person can communicate complex ideas to others. Unless one is a hermit
in a cave, the ability to communicate complex ideas to others is one of
the most important skills any knowledge worker can have.
That said, I'm with Kenny on this one - the only doc I really want to
see is a set of *working* example code that uses the library in
question. This is not because perspicuous written comments would not be
just as useful - they certainly would. It is because I know that in
practice comments and code are so often out of sync that the comments
are simply wrong or misleading as often as not. That being the case,
*working* examples are empirically correct usages of the library which
can be modified to suit one's own use. This is sadly the best one is
going to get in most cases.
Tim X <····@nospam.dev.null> writes:
> I wonder if that's why Knuth's Literate Programming has never really
> taken off. Knuth's perspective was that we need to be able to write
You can find some thoughts on that here:
Anti-Literacy Program
http://airfoyle.blogspot.com/2006/05/anti-literacy-program.html
Paolo
--
Why Lisp? http://wiki.alu.org/RtL%20Highlight%20Film
The Common Lisp Directory: http://www.cl-user.net
From: David Steuber
Subject: Re: Theories on why Lisp source *seems* to have less comments?
Date:
Message-ID: <87d5bpxfbo.fsf@david-steuber.com>
Paolo Amoroso <·······@mclink.it> writes:
> Tim X <····@nospam.dev.null> writes:
>
> > I wonder if that's why Knuth's Literate Programming has never really
> > taken off. Knuth's perspective was that we need to be able to write
>
> You can find some thoughts on that here:
>
> Anti-Literacy Program
> http://airfoyle.blogspot.com/2006/05/anti-literacy-program.html
The extra verbosity doesn't help either. Let's face it. Programmers
are mostly lazy people who don't want to type more than they have to.
Mind you, that laziness pays off when programmers want to make tools
to reduce the amount of typing and debugging that they have to do.
--
The lithobraker. Zero distance stops at any speed.
This post uses 100% post consumer electrons and 100% virgin photons.
At 2.6 miles per minute, you don't really have time to get bored.
--- Pete Roehling on rec.motorcycles
David Steuber wrote:
> Also, keeping comments in sync with the code is a pita when the
> code is not fully formed yet.
If that's the case, you're writing too many comments. :-)
--
Darren New / San Diego, CA, USA (PST)
This octopus isn't tasty. Too many
tentacles, not enough chops.
From: David Steuber
Subject: Re: Theories on why Lisp source *seems* to have less comments?
Date:
Message-ID: <877j1xxf5g.fsf@david-steuber.com>
Darren New <····@san.rr.com> writes:
> David Steuber wrote:
> > Also, keeping comments in sync with the code is a pita when the
> > code is not fully formed yet.
>
> If that's the case, you're writing too many comments. :-)
I've given up on comments. If an employer wants them, I'm willing to
put them in. But they do count against my hourly rate.
--
The lithobraker. Zero distance stops at any speed.
This post uses 100% post consumer electrons and 100% virgin photons.
At 2.6 miles per minute, you don't really have time to get bored.
--- Pete Roehling on rec.motorcycles
"Rob Thorpe" <·············@antenova.com> writes:
> Pascal Costanza wrote:
>> Jonathon McKitrick wrote:
>> > I've found this to be the case in much of the code I've read.
>> > Here are my theories on why:
>> >
>> > 1. Lisp programmers are too busy solving complex problems to document
>> > their code.
>> > 2. Lisp is so powerful it makes programmers lazy, so why waste
>> > keystrokes?
>> > 3. Lisp is more readable, so is more self-documenting.
>> > 4. With docstrings, who needs comments?
>> > 5. It's too hard to type in English after using s-expressions for so
>> > long.
>> >
>> > What do you all think? Any additions?
>>
>> The value of comments is very questionable. It's very likely that
>> comments and code are out of sync because you rarely do both change code
>> and update the comments to reflect the changes. There is no tool that
>> could check whether your comments are still "correct". Comments that are
>> out of sync are potentially more harmful than having no comments.
>>
>> This is actually one of the rationales behind one of the Extreme
>> Programming practices, which is not to comment code. Here are more
>> explanations from the XP crowd:
>
> I've been hearing this a lot recently. Some of it seems to be sensible
> and some fairly nuts to me.
>
I don't believe the XP position is quite as black and white as that.
There is certainly some sense to their position, but I don't think
XP argues for NO comments - rather they are suggesting techniques that
result in less need for comments and move the emphasis away from
relying so heavily on comments.
There is a role for comments. The skill is recognising when to use
them and when not to and not to rely on them as the main explination
of what is going on.
>> - If code is so complicated that you need to comment it for increasing
>> its understandability, it's probably a better idea to rewrite and
>> simplify it.
>
> Yes, if you can simplify it. Some things are just complicated.
True. However, this is more the exception than the rule. Most of what
gets coded is not that complex. I've seen a lot of code which looked
complex, but the real source of that complexity was essentially
programmers who have not got a really solid grasp of either data
structures and abstraction or the right way to use their
tools/language.
As an example, I was given some code to maintain which had some
routines for processing serial numbers which had a specific format and
a checksum that was used to ensure they were valid codes. The bit of
code that checked the validity of these numbers was a couple of
hundred lines long. When I sat down and analysed it, it became obvious
botht eh way the code was being represented and processed were making
things far more complex than necessary. Changing the representation
and adding a few loops rather than if statements reduced the code to
about 50 lines and it ran about 3 times faster.
>
>> - It's better to spend your time on writing test suites, which are
>> actually executable "comments": they illustrate how your code is
>> supposed to be used, and they give you the benefit of showing you what
>> breaks and doesn't break when you make changes to your code. Most of the
>> time, it's actually quite straightforward to formulate your assumptions,
>> requirements, bug reports, etc., as test cases.
>
> IMHO This idea is really evil. Comments get out of date even though
> their right next to the code in question. Unit test however are
> normally in a totally different file, this gives them even less chance
> of staying in date. It also makes things much more difficult for the
> first time reader, a very important audience for comments.
>
I have to disagree here. I've worked in both environments where unit
testing was used extensively and ones where it wasn't and have found
the shop with unit testing was far more productive and produced more
consistent results than the one which relied on comments and
documentation.
Initially, I was someone who was skeptical about unit testing because
I thought it would simply slow down the development process and add
little in real value. However, I realised this was because I wasn't
looking at the bigger picture. Using unit testing does slow down
initial development, but greatly improves on going maintenance and
extension of the system. It is particularly useful when you have a few
people working on a system or a high turn over of staff. When new
functionality is added or existing functionality is changed, its very
easy to ensure the changes have not broken things in other areas you
were not aware of. In large systems, no single person can hope to be
aware of all the interactions and dependencies. Well designed unit
tests relieve the developer from having to have a comprehensive
understanding of all these interactions and dependencies.
I think the secret of unit testing is to actually see the writing of
the unit tests as part of the development process, not as a separate
additional bit of tiresome work which has to be done and which chews
up development time.
>> - It's also relatively straightforward to add assertions and checks to
>> your code that you can switch on (during development) and off (for
>> deployment). This is actually a light-weight form of "design by
>> contract", and also has the effect that you have "executable comments"
>> in your code.
>
> This however is an excellent idea.
>
>> In the case of Lisp I would add that its facilities for functional and
>> syntactic (macro) abstractions give you more possibilities to write
>> "self-documenting" code, i.e., code that declares its intentions instead
>> of spelling out each and every step of its execution.
>
> Yes.
> Another important difference compared to C and C++ is wierdness.
> Many of my comments in C code say something like "this library function
> does something slightly unexpected", or make some remark about header
> namespaces or the semantics of something with innocent syntax. Lisp
> has less wierdness that shows up often.
>
Yes. Thats the sort of comments I think are valuable and which XP
would argue are still required.
--
tcross (at) rapttech dot com dot au
Tim X wrote:
> "Rob Thorpe" <·············@antenova.com> writes:
> > Pascal Costanza wrote:
> >> Jonathon McKitrick wrote:
> >> > I've found this to be the case in much of the code I've read.
> >> > Here are my theories on why:
> >> >
> >> > 1. Lisp programmers are too busy solving complex problems to document
> >> > their code.
> >> > 2. Lisp is so powerful it makes programmers lazy, so why waste
> >> > keystrokes?
> >> > 3. Lisp is more readable, so is more self-documenting.
> >> > 4. With docstrings, who needs comments?
> >> > 5. It's too hard to type in English after using s-expressions for so
> >> > long.
> >> >
> >> > What do you all think? Any additions?
> >>
> >> The value of comments is very questionable. It's very likely that
> >> comments and code are out of sync because you rarely do both change code
> >> and update the comments to reflect the changes. There is no tool that
> >> could check whether your comments are still "correct". Comments that are
> >> out of sync are potentially more harmful than having no comments.
> >>
> >> This is actually one of the rationales behind one of the Extreme
> >> Programming practices, which is not to comment code. Here are more
> >> explanations from the XP crowd:
> >
> > I've been hearing this a lot recently. Some of it seems to be sensible
> > and some fairly nuts to me.
> >
>
> I don't believe the XP position is quite as black and white as that.
It seems to be from this discussion.
> There is certainly some sense to their position, but I don't think
> XP argues for NO comments - rather they are suggesting techniques that
> result in less need for comments and move the emphasis away from
> relying so heavily on comments.
>
> There is a role for comments. The skill is recognising when to use
> them and when not to and not to rely on them as the main explination
> of what is going on.
The problem is, in the absence of comments what explanation is there?
There is only the code, and the code is very flawed as an educational
tool. It often reveals the process to the reader in an order different
than it is done, it spends excessive amounts of time on pedantic
detail. It often uses words that have no meaning outside of the code
of that particular application - and couldn't be described normally.
Often the purpose of code can be described with many fewer words than
take to code it. In this case describing it only with the code only
serves to waste the maintainance programmers time.
> >> - If code is so complicated that you need to comment it for increasing
> >> its understandability, it's probably a better idea to rewrite and
> >> simplify it.
> >
> > Yes, if you can simplify it. Some things are just complicated.
>
> True. However, this is more the exception than the rule. Most of what
> gets coded is not that complex. I've seen a lot of code which looked
> complex, but the real source of that complexity was essentially
> programmers who have not got a really solid grasp of either data
> structures and abstraction or the right way to use their
> tools/language.
I couldn't disagree more. Simple code is by far the exception.
I can't remember the last time I wrote a function simple enough that it
required no explanation at all. Almost everything has some curious
detail that needs remarking on. And of-course it's wise to document
pre-condtions and post-conditions.
> As an example, I was given some code to maintain which had some
> routines for processing serial numbers which had a specific format and
> a checksum that was used to ensure they were valid codes. The bit of
> code that checked the validity of these numbers was a couple of
> hundred lines long. When I sat down and analysed it, it became obvious
> botht eh way the code was being represented and processed were making
> things far more complex than necessary. Changing the representation
> and adding a few loops rather than if statements reduced the code to
> about 50 lines and it ran about 3 times faster.
That's great, but I hope you documented it afterwards. Do you think
most programmers know what a cyclic redundancy check is?
> >> - It's better to spend your time on writing test suites, which are
> >> actually executable "comments": they illustrate how your code is
> >> supposed to be used, and they give you the benefit of showing you what
> >> breaks and doesn't break when you make changes to your code. Most of the
> >> time, it's actually quite straightforward to formulate your assumptions,
> >> requirements, bug reports, etc., as test cases.
> >
> > IMHO This idea is really evil. Comments get out of date even though
> > their right next to the code in question. Unit test however are
> > normally in a totally different file, this gives them even less chance
> > of staying in date. It also makes things much more difficult for the
> > first time reader, a very important audience for comments.
> >
>
> I have to disagree here. I've worked in both environments where unit
> testing was used extensively and ones where it wasn't and have found
> the shop with unit testing was far more productive and produced more
> consistent results than the one which relied on comments and
> documentation.
But why not do both? Unit testing does not mean you *must* write no
documentation, that's only the opinion of XP advocates.
> Initially, I was someone who was skeptical about unit testing because
> I thought it would simply slow down the development process and add
> little in real value. However, I realised this was because I wasn't
> looking at the bigger picture. Using unit testing does slow down
> initial development, but greatly improves on going maintenance and
> extension of the system. It is particularly useful when you have a few
> people working on a system or a high turn over of staff. When new
> functionality is added or existing functionality is changed, its very
> easy to ensure the changes have not broken things in other areas you
> were not aware of. In large systems, no single person can hope to be
> aware of all the interactions and dependencies. Well designed unit
> tests relieve the developer from having to have a comprehensive
> understanding of all these interactions and dependencies.
>
> I think the secret of unit testing is to actually see the writing of
> the unit tests as part of the development process, not as a separate
> additional bit of tiresome work which has to be done and which chews
> up development time.
That's fine, but it has nothing to do with commenting.
Commenting performs a different function than testing, it's information
to the programmer to guide them; An attempt to tell the story of the
program without miring the programmer in absolutely every detail of it.
It's not testing, to use it as such is to abuse it. But the reverse
also applies.
For example XP advocates often say that comment of the form
<complex code>
;; The frob is now in state FOO
<complex code>
Should be turned into assertions ...
<complex code>
(always-assert (check-state frob FOO) "The frob is not in state FOO")
<complex code>
I couldn't agree more. But this is not the whole story, it should also
be mentioned why. I.e.:-
<complex code>
(always-assert (check-state frob FOO) "The frob is not in state FOO")
;; We are using Sheila's algorithm so this condition should be met.
<complex code>
This information is not correctly placed in the error message since it
isn't an error.
> >> - It's also relatively straightforward to add assertions and checks to
> >> your code that you can switch on (during development) and off (for
> >> deployment). This is actually a light-weight form of "design by
> >> contract", and also has the effect that you have "executable comments"
> >> in your code.
> >
> > This however is an excellent idea.
> >
> >> In the case of Lisp I would add that its facilities for functional and
> >> syntactic (macro) abstractions give you more possibilities to write
> >> "self-documenting" code, i.e., code that declares its intentions instead
> >> of spelling out each and every step of its execution.
> >
> > Yes.
> > Another important difference compared to C and C++ is wierdness.
> > Many of my comments in C code say something like "this library function
> > does something slightly unexpected", or make some remark about header
> > namespaces or the semantics of something with innocent syntax. Lisp
> > has less wierdness that shows up often.
> >
>
> Yes. Thats the sort of comments I think are valuable and which XP
> would argue are still required.
Oh good.
You've all made me very glad I'm not a professional programmer anymore
today.
"Rob Thorpe" <·············@antenova.com> writes:
> Tim X wrote:
>> "Rob Thorpe" <·············@antenova.com> writes:
>> > Pascal Costanza wrote:
>> >> Jonathon McKitrick wrote:
>> >> > I've found this to be the case in much of the code I've read.
>> >> > Here are my theories on why:
>> >> >
>> >> > 1. Lisp programmers are too busy solving complex problems to document
>> >> > their code.
>> >> > 2. Lisp is so powerful it makes programmers lazy, so why waste
>> >> > keystrokes?
>> >> > 3. Lisp is more readable, so is more self-documenting.
>> >> > 4. With docstrings, who needs comments?
>> >> > 5. It's too hard to type in English after using s-expressions for so
>> >> > long.
>> >> >
>> >> > What do you all think? Any additions?
>> >>
>> >> The value of comments is very questionable. It's very likely that
>> >> comments and code are out of sync because you rarely do both change code
>> >> and update the comments to reflect the changes. There is no tool that
>> >> could check whether your comments are still "correct". Comments that are
>> >> out of sync are potentially more harmful than having no comments.
>> >>
>> >> This is actually one of the rationales behind one of the Extreme
>> >> Programming practices, which is not to comment code. Here are more
>> >> explanations from the XP crowd:
>> >
>> > I've been hearing this a lot recently. Some of it seems to be sensible
>> > and some fairly nuts to me.
>> >
>>
>> I don't believe the XP position is quite as black and white as that.
>
> It seems to be from this discussion.
>
Thats partially why I chimed in to say it wasn't an "all or nothing"
situation. Nothing in XP prevents you from adding comments. I see it
more as moving the focus to other tools/approaches which in some areas
provides equivalent information plus other advantages that comments
alone don't while avoiding the problem of keeping comments current.
>> There is certainly some sense to their position, but I don't think
>> XP argues for NO comments - rather they are suggesting techniques that
>> result in less need for comments and move the emphasis away from
>> relying so heavily on comments.
>>
>> There is a role for comments. The skill is recognising when to use
>> them and when not to and not to rely on them as the main explination
>> of what is going on.
>
> The problem is, in the absence of comments what explanation is there?
> There is only the code, and the code is very flawed as an educational
> tool. It often reveals the process to the reader in an order different
> than it is done, it spends excessive amounts of time on pedantic
> detail. It often uses words that have no meaning outside of the code
> of that particular application - and couldn't be described normally.
>
> Often the purpose of code can be described with many fewer words than
> take to code it. In this case describing it only with the code only
> serves to waste the maintainance programmers time.
>
Again, you still seem to be ssing it as an all or nothing situation.
>> >> - If code is so complicated that you need to comment it for increasing
>> >> its understandability, it's probably a better idea to rewrite and
>> >> simplify it.
>> >
>> > Yes, if you can simplify it. Some things are just complicated.
>>
>> True. However, this is more the exception than the rule. Most of what
>> gets coded is not that complex. I've seen a lot of code which looked
>> complex, but the real source of that complexity was essentially
>> programmers who have not got a really solid grasp of either data
>> structures and abstraction or the right way to use their
>> tools/language.
>
> I couldn't disagree more. Simple code is by far the exception.
> I can't remember the last time I wrote a function simple enough that it
> required no explanation at all. Almost everything has some curious
> detail that needs remarking on. And of-course it's wise to document
> pre-condtions and post-conditions.
>
Certainly not my experience - even less so with the rapid growth of
languages with large standard libraries and easily obtained add on
libraries. Of course, we could also be using different definitions of
complexity.
Most of the code I see is pretty straight forward - it is generally
built from blocks of pretty common algorithms and language specific
axioms. Probably less than 20% of what I see is particularly complex
or hard to understand (assuming it has ben written with good variable
names, data abstraction and using language features appropriately).
>> As an example, I was given some code to maintain which had some
>> routines for processing serial numbers which had a specific format and
>> a checksum that was used to ensure they were valid codes. The bit of
>> code that checked the validity of these numbers was a couple of
>> hundred lines long. When I sat down and analysed it, it became obvious
>> botht eh way the code was being represented and processed were making
>> things far more complex than necessary. Changing the representation
>> and adding a few loops rather than if statements reduced the code to
>> about 50 lines and it ran about 3 times faster.
>
> That's great, but I hope you documented it afterwards. Do you think
> most programmers know what a cyclic redundancy check is?
>
I documented it with a high level explination at the top of the file -
from memory, about 5 lines. I usually document purpose/return value of
functions - in lisp as part of the docstring and in other languages, a
one liner at the beginning if the name is not explination enough.
>> >> - It's better to spend your time on writing test suites, which are
>> >> actually executable "comments": they illustrate how your code is
>> >> supposed to be used, and they give you the benefit of showing you what
>> >> breaks and doesn't break when you make changes to your code. Most of the
>> >> time, it's actually quite straightforward to formulate your assumptions,
>> >> requirements, bug reports, etc., as test cases.
>> >
>> > IMHO This idea is really evil. Comments get out of date even though
>> > their right next to the code in question. Unit test however are
>> > normally in a totally different file, this gives them even less chance
>> > of staying in date. It also makes things much more difficult for the
>> > first time reader, a very important audience for comments.
>> >
>>
>> I have to disagree here. I've worked in both environments where unit
>> testing was used extensively and ones where it wasn't and have found
>> the shop with unit testing was far more productive and produced more
>> consistent results than the one which relied on comments and
>> documentation.
>
> But why not do both? Unit testing does not mean you *must* write no
> documentation, that's only the opinion of XP advocates.
>
But thats the point. I don't believe XP says NO documentation.
>> Initially, I was someone who was skeptical about unit testing because
>> I thought it would simply slow down the development process and add
>> little in real value. However, I realised this was because I wasn't
>> looking at the bigger picture. Using unit testing does slow down
>> initial development, but greatly improves on going maintenance and
>> extension of the system. It is particularly useful when you have a few
>> people working on a system or a high turn over of staff. When new
>> functionality is added or existing functionality is changed, its very
>> easy to ensure the changes have not broken things in other areas you
>> were not aware of. In large systems, no single person can hope to be
>> aware of all the interactions and dependencies. Well designed unit
>> tests relieve the developer from having to have a comprehensive
>> understanding of all these interactions and dependencies.
>>
>> I think the secret of unit testing is to actually see the writing of
>> the unit tests as part of the development process, not as a separate
>> additional bit of tiresome work which has to be done and which chews
>> up development time.
>
> That's fine, but it has nothing to do with commenting.
> Commenting performs a different function than testing, it's information
> to the programmer to guide them; An attempt to tell the story of the
> program without miring the programmer in absolutely every detail of it.
> It's not testing, to use it as such is to abuse it. But the reverse
> also applies.
>
Testing per se is not a replacement for comments. However, unit
testing does contribute to code understanding as it explicitly shows
what is and is not expected. Of course, just like bad comments, you
can have badly designed/implemented unit tests.
--
tcross (at) rapttech dot com dot au
From: Pascal Costanza
Subject: Re: Theories on why Lisp source *seems* to have less comments?
Date:
Message-ID: <4ieligF3dts7U1@individual.net>
Rob Thorpe wrote:
> Pascal Costanza wrote:
>> The value of comments is very questionable. It's very likely that
>> comments and code are out of sync because you rarely do both change code
>> and update the comments to reflect the changes. There is no tool that
>> could check whether your comments are still "correct". Comments that are
>> out of sync are potentially more harmful than having no comments.
>>
>> This is actually one of the rationales behind one of the Extreme
>> Programming practices, which is not to comment code. Here are more
>> explanations from the XP crowd:
>
> I've been hearing this a lot recently.
Come on - it's not that new anymore... ;)
> Some of it seems to be sensible
> and some fairly nuts to me.
>
>> - If code is so complicated that you need to comment it for increasing
>> its understandability, it's probably a better idea to rewrite and
>> simplify it.
>
> Yes, if you can simplify it. Some things are just complicated.
True.
>> - It's better to spend your time on writing test suites, which are
>> actually executable "comments": they illustrate how your code is
>> supposed to be used, and they give you the benefit of showing you what
>> breaks and doesn't break when you make changes to your code. Most of the
>> time, it's actually quite straightforward to formulate your assumptions,
>> requirements, bug reports, etc., as test cases.
>
> IMHO This idea is really evil. Comments get out of date even though
> their right next to the code in question.
Exactly.
> Unit test however are
> normally in a totally different file, this gives them even less chance
> of staying in date.
Incorrect. An important ingredient here is that it should be
straightforward to run the test suites, so that you do it more often.
> It also makes things much more difficult for the
> first time reader, a very important audience for comments.
It's indeed an acknowledged problem of XP that people who are new to a
project have a hard time to find their way around. This is somewhat
compensated for by the practices of pair programming (where newbies are
paired with more experienced members of a team), no code ownership and
regular changes of teams.
However, this becomes especially problematic for "version 2.0" projects,
where it is likely the case that people from the original team are not
available anymore. Then the lack of documentation due to XP's disregard
for producing it can really hurt. AFAICT, XP doesn't have a good answer
in this regard.
In most other regards, XP seems to work (to some surprisingly) well.
>> - It's also relatively straightforward to add assertions and checks to
>> your code that you can switch on (during development) and off (for
>> deployment). This is actually a light-weight form of "design by
>> contract", and also has the effect that you have "executable comments"
>> in your code.
>
> This however is an excellent idea.
>
>> In the case of Lisp I would add that its facilities for functional and
>> syntactic (macro) abstractions give you more possibilities to write
>> "self-documenting" code, i.e., code that declares its intentions instead
>> of spelling out each and every step of its execution.
>
> Yes.
> Another important difference compared to C and C++ is wierdness.
> Many of my comments in C code say something like "this library function
> does something slightly unexpected", or make some remark about header
> namespaces or the semantics of something with innocent syntax. Lisp
> has less wierdness that shows up often.
>
--
My website: http://p-cos.net
Closer to MOP & ContextL:
http://common-lisp.net/project/closer/
> IMHO This idea is really evil. Comments get out of date even though
> their right next to the code in question. Unit test however are
> normally in a totally different file, this gives them even less chance
> of staying in date.
Whaaaa? Unit tests have the wonderful property of being
automatically checkable for consistency -- just run them!
This means they will be *much* easier to keep in sync with
the code.
Paul
From: Maciek Pasternacki
Subject: Re: Theories on why Lisp source *seems* to have less comments?
Date:
Message-ID: <87hd17nr3z.fsf@japhy.fnord.org>
On Pungenday, Confusion 57, 3172 YOLD, Rob Thorpe wrote:
>> - It's better to spend your time on writing test suites, which are
>> actually executable "comments": they illustrate how your code is
>> supposed to be used, and they give you the benefit of showing you what
>> breaks and doesn't break when you make changes to your code. Most of the
>> time, it's actually quite straightforward to formulate your assumptions,
>> requirements, bug reports, etc., as test cases.
>
> IMHO This idea is really evil. Comments get out of date even though
> their right next to the code in question. Unit test however are
> normally in a totally different file, this gives them even less chance
> of staying in date. It also makes things much more difficult for the
> first time reader, a very important audience for comments.
And when you write unit tests *in* docstrings?
http://docs.python.org/lib/module-doctest.html
In Lisp it might not exactly be docstrings (why parse if we have sexps
at hand?) but some macrology could do fine.
--
-><- This signature intentionally left blank. -><-
Maciek Pasternacki wrote:
> On Pungenday, Confusion 57, 3172 YOLD, Rob Thorpe wrote:
>
> >> - It's better to spend your time on writing test suites, which are
> >> actually executable "comments": they illustrate how your code is
> >> supposed to be used, and they give you the benefit of showing you what
> >> breaks and doesn't break when you make changes to your code. Most of the
> >> time, it's actually quite straightforward to formulate your assumptions,
> >> requirements, bug reports, etc., as test cases.
> >
> > IMHO This idea is really evil. Comments get out of date even though
> > their right next to the code in question. Unit test however are
> > normally in a totally different file, this gives them even less chance
> > of staying in date. It also makes things much more difficult for the
> > first time reader, a very important audience for comments.
>
> And when you write unit tests *in* docstrings?
> http://docs.python.org/lib/module-doctest.html
>
> In Lisp it might not exactly be docstrings (why parse if we have sexps
> at hand?) but some macrology could do fine.
That is a good idea, as far as I can see.
Most examples of XP I've seen don't seem to do it though. I don't know
why.
"Rob Thorpe" <·············@antenova.com> writes:
> Maciek Pasternacki wrote:
>> On Pungenday, Confusion 57, 3172 YOLD, Rob Thorpe wrote:
>> And when you write unit tests *in* docstrings?
>> http://docs.python.org/lib/module-doctest.html
>>
>> In Lisp it might not exactly be docstrings (why parse if we have sexps
>> at hand?) but some macrology could do fine.
From day one you can write:
(declaim (declaraction test-case))
(defun fact (n)
(declare
(test-case (mapcar (function fact) (iota 6)) '(1 1 2 6 24 120))
(test-case (fact 30) 265252859812191058636308480000000)
(test-case (typep (nth-value 1 (ignore-errors (fact -1)))) 'error)
(test-case (values 1 2 3) 1 2 3))
(cond ((< n 0) (error "Invalid parameter for FACT ~A" n))
((= n 0) 1)
(t (* n (fact (1- n))))))
Reading and testing the test-case declarations is rather trivial,
exercise left to the student.
--
__Pascal Bourguignon__ http://www.informatimago.com/
"Logiciels libres : nourris au code source sans farine animale."
From: Pascal Costanza
Subject: Re: Theories on why Lisp source *seems* to have less comments?
Date:
Message-ID: <4ik39kF431qvU1@individual.net>
Pascal Bourguignon wrote:
> "Rob Thorpe" <·············@antenova.com> writes:
>> Maciek Pasternacki wrote:
>>> On Pungenday, Confusion 57, 3172 YOLD, Rob Thorpe wrote:
>>> And when you write unit tests *in* docstrings?
>>> http://docs.python.org/lib/module-doctest.html
>>>
>>> In Lisp it might not exactly be docstrings (why parse if we have sexps
>>> at hand?) but some macrology could do fine.
>
>
> From day one you can write:
>
>
> (declaim (declaraction test-case))
>
> (defun fact (n)
> (declare
> (test-case (mapcar (function fact) (iota 6)) '(1 1 2 6 24 120))
> (test-case (fact 30) 265252859812191058636308480000000)
> (test-case (typep (nth-value 1 (ignore-errors (fact -1)))) 'error)
> (test-case (values 1 2 3) 1 2 3))
> (cond ((< n 0) (error "Invalid parameter for FACT ~A" n))
> ((= n 0) 1)
> (t (* n (fact (1- n))))))
>
>
> Reading and testing the test-case declarations is rather trivial,
> exercise left to the student.
This is intriguing.
Pascal
--
My website: http://p-cos.net
Closer to MOP & ContextL:
http://common-lisp.net/project/closer/
Pascal Costanza <··@p-cos.net> writes:
> Pascal Bourguignon wrote:
>> "Rob Thorpe" <·············@antenova.com> writes:
>>> Maciek Pasternacki wrote:
>>>> On Pungenday, Confusion 57, 3172 YOLD, Rob Thorpe wrote:
>>>> And when you write unit tests *in* docstrings?
>>>> http://docs.python.org/lib/module-doctest.html
>>>>
>>>> In Lisp it might not exactly be docstrings (why parse if we have sexps
>>>> at hand?) but some macrology could do fine.
>> From day one you can write:
>> (declaim (declaraction test-case))
>> (defun fact (n)
>> (declare
>> (test-case (mapcar (function fact) (iota 6)) '(1 1 2 6 24 120))
>> (test-case (fact 30) 265252859812191058636308480000000)
>> (test-case (typep (nth-value 1 (ignore-errors (fact -1)))) 'error)
I mean:
(test-case (not (typep (nth-value 1 (ignore-errors (fact -1))) 'error))
nil)
Some utility functions and macro provided by the test-case DSL will
come handy.
>> (test-case (values 1 2 3) 1 2 3))
>> (cond ((< n 0) (error "Invalid parameter for FACT ~A" n))
>> ((= n 0) 1)
>> (t (* n (fact (1- n))))))
>> Reading and testing the test-case declarations is rather trivial,
>> exercise left to the student.
>
> This is intriguing.
>
>
> Pascal
>
> --
> My website: http://p-cos.net
> Closer to MOP & ContextL:
> http://common-lisp.net/project/closer/
--
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?
A: Top-posting.
Q: What is the most annoying thing on usenet and in e-mail?
__Pascal Bourguignon__ http://www.informatimago.com/
"Jonathon McKitrick" <···········@bigfoot.com> writes:
> I've found this to be the case in much of the code I've read.
> Here are my theories on why:
>
> 1. Lisp programmers are too busy solving complex problems to document
> their code.
> 2. Lisp is so powerful it makes programmers lazy, so why waste
> keystrokes?
> 3. Lisp is more readable, so is more self-documenting.
> 4. With docstrings, who needs comments?
> 5. It's too hard to type in English after using s-expressions for so
> long.
>
My experience has been that most code comments are next to useless.
How often do you see something like
x = 10 // set x to 10
Maybe slightly exaggerated, but you get the idea.
I think points 3 and 4 are the crucial ones. Lisp is very easy to read
compared to many other languages and the docstring generally gives you
the basic high level objective of the code.
I also think the tendency to code in shorter functions etc, make it
easier to follow. I've seen cryptic C and C++ code where functions are
very large and often perform multiple tasks - without the code
comments, you would be struggling to get every aspect.
Of course, you can write impossible to understand code in any
language. Lisp does tend to discourage such things a bit more than C
or C++. then you have perl - wonderful selection of special variables
and operators that make coding very efficient - but I've seen a lot of
perl code that reminds me of what was often seen back with early
modems and was usually referred to as line noise - collections of
apparently random meaningless characters etc.
Tim
--
tcross (at) rapttech dot com dot au
> My experience has been that most code comments are next to useless.
> How often do you see something like
>
> x = 10 // set x to 10
>
> Maybe slightly exaggerated, but you get the idea.
I've discovered an odd phenomenon in my recent coding. Early on in the
implementation of some functionality, I find myself commenting the code
a lot, as if to remind myself what I am thinking at the time, and to
help pick up where I left off. But as the solution becomes more
defined and is show to be correct, I find myself deleting the comments
as redundant, though hopefully not so bad as your example.
Jonathon McKitrick wrote:
> > My experience has been that most code comments are next to useless.
> > How often do you see something like
> >
> > x = 10 // set x to 10
> >
> > Maybe slightly exaggerated, but you get the idea.
>
> I've discovered an odd phenomenon in my recent coding. Early on in the
> implementation of some functionality, I find myself commenting the code
> a lot, as if to remind myself what I am thinking at the time, and to
> help pick up where I left off. But as the solution becomes more
> defined and is show to be correct, I find myself deleting the comments
> as redundant, though hopefully not so bad as your example.
I've done that. I prepend those comments with ";; WRITING" so I can
delete them once the code is complete.
After you've written something it falls into three categories.
* It's exactly as you thought it would be, you can leave your comments
alone.
* It's more arbitrary than you thought, in which case it probably needs
more.
* It fits into some kind of idiom or known algorithm. In which case
probably a load of comments need deleting and a comment added at the
very start explaining this clearly.
From: Steven E. Harris
Subject: Re: Theories on why Lisp source *seems* to have less comments?
Date:
Message-ID: <83bqridzur.fsf@torus.sehlabs.com>
Tim X <····@nospam.dev.null> writes:
> How often do you see something like
>
> x = 10 // set x to 10
>
> Maybe slightly exaggerated, but you get the idea.
One idiom I've seen a lot of in C and C++ -- typical of less mature
programmers -- is the function "plan" left in comment form. The
programmer starts off facing a daunting task by writing a series of
imperative steps as comments:
// Open the file.
// Read each line.
// Does this line start with "cheese"?
// Yes! Let's now try to read what kind of cheese...
// ...
// Close the file.
// Return the result.
The programmer starts filling in code for these steps, usually amidst
the same burgeoning function, and leaves the comments in place --
partly because the smaller steps have not been bundled up in helper
functions. The comments serve as headings to break up the 500-line
mess. It's also frightening to note how often these commented steps go
unimplemented, such as the error cases.
This kind of writing process doesn't work well in Lisp. Perhaps the
initial laying out of steps could be useful, but the code won't settle
in and among the comments as easily. A Lisp author is more likely to
go and create the smaller helper functions, and is more likely to
chain function calls and return values, with the expression tree
growing deeper before it grows wider. The comments get squeezed out,
as they should.
--
Steven E. Harris
Tim X <····@nospam.dev.null> wrote:
+---------------
| My experience has been that most code comments are next to useless.
| How often do you see something like
| x = 10 // set x to 10
| Maybe slightly exaggerated, but you get the idea.
+---------------
Far too often, unfortunately.
The TOPS-10 5-Series Monitor Coding Conventions (LEVELD.MEM)
prescribed a comment on every line [but this *was* all in
assembler, after all!]. But the rule was that you *never* used
the comment to describe *what* an instruction did -- the reader
is presumed to know the language in question -- but *why* the
instruction (or short sequence of instructions) was being used,
or other higher-level information such as particularly tricky
algorithms.
-Rob
-----
Rob Warnock <····@rpw3.org>
627 26th Avenue <URL:http://rpw3.org/>
San Mateo, CA 94403 (650)572-2607
From: Kent M Pitman
Subject: Re: Theories on why Lisp source *seems* to have less comments?
Date:
Message-ID: <u1wsdp4xl.fsf@nhplace.com>
"Jonathon McKitrick" <···········@bigfoot.com> writes:
> I've found this to be the case in much of the code I've read.
> Here are my theories on why:
>
> 1. Lisp programmers are too busy solving complex problems to document
> their code.
No.
> 2. Lisp is so powerful it makes programmers lazy, so why waste
> keystrokes?
No.
> 3. Lisp is more readable, so is more self-documenting.
Not exactly. But see below.
> 4. With docstrings, who needs comments?
Docstrings are comments, so this makes no sense.
> 5. It's too hard to type in English after using s-expressions for so
> long.
No.
> What do you all think? Any additions?
I would add negations of most of the above. Then I would also add:
1. Lisp doesn't waste space on stupid syntax (like braces on their own
lines) so has a bit of space available for longer function names on
lines that contain overrun from long names.
2. Lisp allows and encourages long names, so people feel free to use them.
3. The use of hyphen-separated-names is easier to read than
NamesInStudlyCaps and easier to type than underscore_separated_names.
4. Lisp, not being "statically type checked", relies on common sense
naming to help people visibly recognize what's going on.
Typical Lisp:
(setq *master-frobs*
(list (make-frob-named (widget-suggested-name (find-widget ...)))))
where you notice that find-WIDGET returns a widget, which is what
the function WIDGET-suggested-name expects. It's easy to match up
the -WIDGET and WIDGET- and understand what's going on. Likewise,
suggested-NAME and make-frob-NAMED are easy to see match. And
*MASTER-FROBS* is clearly something expecting a list of frobs, so
(LIST (MAKE-FROB-named ...) ...) is easy to as as right.
Typical C/C++/Java/whatever equivalent:
vFrobL = IFrob(WFind(...).sname);
People don't tend to encode error-checking information into their
names in these other languages because (a) it's studly (not to
mention job security to make obscure names) and (b) they think the
compiler will tell them if they've goofed up.
Put another ways, what people often target as a weakness of Lisp
(lack of static type checking) is made up for by good programmers
writing clearer programs, and program readability (not an inherent
feature of Lisp, but a side-effect of this kind of defensive
programming) benefits.
I claim this is why you have to look at a whole language ecology
and not just at an isolated feature when trying to evaluate its
goodness.
5. The availability of APROPOS and other dynamic debugging tools also
encourage good naming so that libraries will be easily searchable.
6. This answer is somewhat subjective, and probably not true for all
programmers, but is probably true for enough programmers that it's
worth mentioning:
The fact that Lisp appeals to the people who believe in the
"program is data and data is program" paradigm. As such, Lisp
programmers think of the code as a descriptive work, not just an
implementation work. (This isn't, then, a property of Lisp per se,
but is correlated with the personality type to whom Lisp appeals.)
Lisp programmers work harder, as a matter of their self-selected
personality type, to get the "meaning" of the program into the
program--because they want the program itself to endure as a
programmatic description of something, not just as a programmatic
implementation.
On Sat, 22 Jul 2006 23:54:43 +0000, Kent M Pitman wrote:
> "Jonathon McKitrick" <···········@bigfoot.com> writes:
>
>> 3. Lisp is more readable, so is more self-documenting.
>
> Not exactly. But see below.
It is easier to make Lisp readable. Macros are an obvious example of this,
but so is the functional style and the concomitant proliferation of
higher-order functions that replace what would be rather complex control
structures in languages closer to the Algol family.
>
>> 4. With docstrings, who needs comments?
>
> Docstrings are comments, so this makes no sense.
Correction: Docstrings are comments available at the REPL that exist even
after the function they're attached to has been compiled into pure machine
code. Python is the only other language I know that has anything like them.
> 4. Lisp, not being "statically type checked", relies on common sense
> naming to help people visibly recognize what's going on.
>
> Typical Lisp:
>
> (setq *master-frobs*
> (list (make-frob-named (widget-suggested-name (find-widget ...)))))
>
> where you notice that find-WIDGET returns a widget, which is what
> the function WIDGET-suggested-name expects. It's easy to match up
> the -WIDGET and WIDGET- and understand what's going on. Likewise,
> suggested-NAME and make-frob-NAMED are easy to see match. And
> *MASTER-FROBS* is clearly something expecting a list of frobs, so
> (LIST (MAKE-FROB-named ...) ...) is easy to as as right.
>
This kind of semantic Hungarian notation (that is, encoding in the
variable name the kind of type information no compiler can check) is what
Hungarian notation was originally designed to be. The useless abomination
it became is why programmers shudder at its mention.
> The fact that Lisp appeals to the people who believe in the
> "program is data and data is program" paradigm. As such, Lisp
> programmers think of the code as a descriptive work, not just an
> implementation work.
All this is very much aided by macros, which allow programmers to remake
the language in the problem's image. The need for comments decreases when
you have all the 'obvious' control structures and functions defined in
terms of the problem domain, something helped even more by the correct use
of Hungarian notation.
--
My address happens to be com (dot) gmail (at) usenet (plus) chbarts,
wardsback and translated.
It's in my header if you need a spoiler.
----== Posted via Newsfeeds.Com - Unlimited-Unrestricted-Secure Usenet News==----
http://www.newsfeeds.com The #1 Newsgroup Service in the World! 120,000+ Newsgroups
----= East and West-Coast Server Farms - Total Privacy via Encryption =----
Chris Barts <··············@tznvy.pbz> writes:
> Correction: Docstrings are comments available at the REPL that exist even
> after the function they're attached to has been compiled into pure machine
> code. Python is the only other language I know that has anything like them.
What about Smalltalk?
Paolo
--
Why Lisp? http://wiki.alu.org/RtL%20Highlight%20Film
The Common Lisp Directory: http://www.cl-user.net
Paolo Amoroso <·······@mclink.it> wrote:
+---------------
| Chris Barts <··············@tznvy.pbz> writes:
| > Correction: Docstrings are comments available at the REPL that exist even
| > after the function they're attached to has been compiled into pure machine
| > code. Python is the only other language I know that has anything like them.
|
| What about Smalltalk?
+---------------
Or Tcl?
-Rob
-----
Rob Warnock <····@rpw3.org>
627 26th Avenue <URL:http://rpw3.org/>
San Mateo, CA 94403 (650)572-2607
····@rpw3.org (Rob Warnock) writes:
> Paolo Amoroso <·······@mclink.it> wrote:
> +---------------
> | Chris Barts <··············@tznvy.pbz> writes:
> | > Correction: Docstrings are comments available at the REPL that exist even
> | > after the function they're attached to has been compiled into pure machine
> | > code. Python is the only other language I know that has anything like them.
> |
> | What about Smalltalk?
> +---------------
>
> Or Tcl?
>
>
> -Rob
>
compiled Tcl?
--
tcross (at) rapttech dot com dot au
Tim X <····@nospam.dev.null> wrote:
+---------------
| ····@rpw3.org (Rob Warnock) writes:
| > Or Tcl?
|
| compiled Tcl?
+---------------
Dunno, sorry. I've never [knowingly] used compiled Tcl.
Mostly I just use the fact the it stores procedure arglists
and bodies where they can be recovered/printed, e.g.:
tcl>proc foo {a b} {
=># "FOO A B" adds A & B and returns the sum.
=>expr $a + $b
=>}
tcl>foo 12 34
46
tcl>
Then, later:
tcl>info args foo
a b
tcl>info body foo
# "FOO A B" adds A & B and returns the sum.
expr $a + $b
tcl>
But for a more formal docstring-only retrieval system, you
might want something like this <http://wiki.tcl.tk/10793>.
-Rob
-----
Rob Warnock <····@rpw3.org>
627 26th Avenue <URL:http://rpw3.org/>
San Mateo, CA 94403 (650)572-2607
Rob Warnock <····@rpw3.org> wrote:
[...]
>
> Then, later:
>
> tcl>info args foo
> a b
> tcl>info body foo
>
> # "FOO A B" adds A & B and returns the sum.
> expr $a + $b
>
Is there a Lisp equivalent for this? I wanted something like "info body
foo" the other day in the REPL.
····@stablecross.com (Bob Felts) writes:
> Rob Warnock <····@rpw3.org> wrote:
>
> [...]
>
>>
>> Then, later:
>>
>> tcl>info args foo
>> a b
>> tcl>info body foo
>>
>> # "FOO A B" adds A & B and returns the sum.
>> expr $a + $b
>>
>
> Is there a Lisp equivalent for this? I wanted something like "info body
> foo" the other day in the REPL.
[36]> (defun foo (a b) "(FOO A B) returns the sum of A and B" (+ a b))
FOO
[37]> (function-lambda-expression 'foo)
(LAMBDA (A B) "(FOO A B) returns the sum of A and B"
(DECLARE (SYSTEM::IN-DEFUN FOO)) (BLOCK FOO (+ A B))) ;
#(NIL NIL NIL NIL ((DECLARATION XLIB::CLX-VALUES VALUES OPTIMIZE DECLARATION))) ;
FOO
The only problem is that the standard allows implementations to always
return NIL. Choose your implementation wisely!
You can write:
(defun function-arguments (f) (cadr (function-lambda-expression f)))
(defun function-body (f) (cddr (function-lambda-expression f)))
[42]> (function-arguments 'foo)
(A B)
[43]> (function-body 'foo)
("(FOO A B) returns the sum of A and B" (+ A B))
--
__Pascal Bourguignon__ http://www.informatimago.com/
Until real software engineering is developed, the next best practice
is to develop with a dynamic system that has extreme late binding in
all aspects. The first system to really do this in an important way
is Lisp. -- Alan Kay
From: Waldek Hebisch
Subject: Re: Theories on why Lisp source *seems* to have less comments?
Date:
Message-ID: <ea5rif$2c7$1@panorama.wcss.wroc.pl>
Pascal Bourguignon <···@informatimago.com> wrote:
>
> [36]> (defun foo (a b) "(FOO A B) returns the sum of A and B" (+ a b))
> FOO
> [37]> (function-lambda-expression 'foo)
> (LAMBDA (A B) "(FOO A B) returns the sum of A and B"
> (DECLARE (SYSTEM::IN-DEFUN FOO)) (BLOCK FOO (+ A B))) ;
> #(NIL NIL NIL NIL ((DECLARATION XLIB::CLX-VALUES VALUES OPTIMIZE DECLARATION))) ;
> FOO
>
> The only problem is that the standard allows implementations to always
> return NIL. Choose your implementation wisely!
>
>
You mean: use Clisp? Of four Lisp implementations one have no
function-lambda-expression, two barf on:
(function-lambda-expression 'foo)
and want:
(function-lambda-expression #'foo)
but then produce:
NIL
T
FOO
And only Clisp gives your output.
--
Waldek Hebisch
·······@math.uni.wroc.pl
Waldek Hebisch wrote:
> Pascal Bourguignon <···@informatimago.com> wrote:
> >
> > [36]> (defun foo (a b) "(FOO A B) returns the sum of A and B" (+ a b))
> > FOO
> > [37]> (function-lambda-expression 'foo)
> > (LAMBDA (A B) "(FOO A B) returns the sum of A and B"
> > (DECLARE (SYSTEM::IN-DEFUN FOO)) (BLOCK FOO (+ A B))) ;
> > #(NIL NIL NIL NIL ((DECLARATION XLIB::CLX-VALUES VALUES OPTIMIZE DECLARATION))) ;
> > FOO
> >
> > The only problem is that the standard allows implementations to always
> > return NIL. Choose your implementation wisely!
> >
> >
>
> You mean: use Clisp? Of four Lisp implementations one have no
> function-lambda-expression, two barf on:
>
> (function-lambda-expression 'foo)
>
> and want:
>
> (function-lambda-expression #'foo)
>
> but then produce:
>
> NIL
> T
> FOO
>
> And only Clisp gives your output.
Something a little more portable:
(eval-when (:compile-toplevel :load-toplevel :execute)
(shadow 'defun))
(defmacro defun (name args &body body)
`(progn
(setf (get ',name 'body) '(,name ,args ,@body))
(cl:defun ,name ,args ,@body)))
(defun foo (x)
(+ 12 x))
(print (get 'foo 'body))
>
> --
> Waldek Hebisch
> ·······@math.uni.wroc.pl
From: Ken Tilton
Subject: Re: Theories on why Lisp source *seems* to have less comments?
Date:
Message-ID: <0ixxg.4194$Qn6.3987@fe09.lga>
Waldek Hebisch wrote:
> Pascal Bourguignon <···@informatimago.com> wrote:
>
>>[36]> (defun foo (a b) "(FOO A B) returns the sum of A and B" (+ a b))
>>FOO
>>[37]> (function-lambda-expression 'foo)
>>(LAMBDA (A B) "(FOO A B) returns the sum of A and B"
>> (DECLARE (SYSTEM::IN-DEFUN FOO)) (BLOCK FOO (+ A B))) ;
>>#(NIL NIL NIL NIL ((DECLARATION XLIB::CLX-VALUES VALUES OPTIMIZE DECLARATION))) ;
>>FOO
>>
>>The only problem is that the standard allows implementations to always
>>return NIL. Choose your implementation wisely!
>>
>>
>
>
> You mean: use Clisp? Of four Lisp implementations one have no
> function-lambda-expression, two barf on:
>
> (function-lambda-expression 'foo)
>
> and want:
>
> (function-lambda-expression #'foo)
>
> but then produce:
>
> NIL
> T
> FOO
>
> And only Clisp gives your output.
>
Try control-x-d or whatever the keychord is for "show documentation".
kt
--
Cells: http://common-lisp.net/project/cells/
"I'll say I'm losing my grip, and it feels terrific."
-- Smiling husband to scowling wife, New Yorker cartoon
Waldek Hebisch schrieb:
> Pascal Bourguignon <···@informatimago.com> wrote:
> >
> > [36]> (defun foo (a b) "(FOO A B) returns the sum of A and B" (+ a b))
> > FOO
> > [37]> (function-lambda-expression 'foo)
> > (LAMBDA (A B) "(FOO A B) returns the sum of A and B"
> > (DECLARE (SYSTEM::IN-DEFUN FOO)) (BLOCK FOO (+ A B))) ;
> > #(NIL NIL NIL NIL ((DECLARATION XLIB::CLX-VALUES VALUES OPTIMIZE DECLARATION))) ;
> > FOO
> >
> > The only problem is that the standard allows implementations to always
> > return NIL. Choose your implementation wisely!
> >
> >
>
> You mean: use Clisp? Of four Lisp implementations one have no
> function-lambda-expression, two barf on:
> (function-lambda-expression 'foo)
This is not valid according to the standard. The argument to
FUNCTION-LAMBDA-EXPRESSION must be a function itself.
http://www.lispworks.com/documentation/HyperSpec/Body/f_fn_lam.htm#function-lambda-expression
as in...
> and want:
> (function-lambda-expression #'foo)
> And only Clisp gives your output.
ECL does as well if you have _not_ compiled the function to C, a
process which eliminates the source due to space considerations.
ECL (Embeddable Common-Lisp) 0.9i
Copyright (C) 1984 Taiichi Yuasa and Masami Hagiya
Copyright (C) 1993 Giuseppe Attardi
Copyright (C) 2000 Juan J. Garcia-Ripoll
ECL is free software, and you are welcome to redistribute it
under certain conditions; see file 'Copyright' for details.
Type :h for Help. Broken at EVAL.
> (defun foo (a b) "(FOO A B) returns the sum of A and B" (+ a b))
FOO
> (function-lambda-expression 'foo)
FOO is not of type FUNCTION.
Broken at FUNCTION-LAMBDA-EXPRESSION.
>> :q
Broken at EVAL.
> (function-lambda-expression #'foo)
(SI:LAMBDA-BLOCK FOO (A B) (+ A B))
NIL
FOO
Notice that SI:LAMBDA-BLOCK is a macro proper to ECL that expands to
something like (lambda (a b) (block foo (+ a b))).
Cheers
Juanjo
From: Lars Brinkhoff
Subject: Re: Theories on why Lisp source *seems* to have less comments?
Date:
Message-ID: <85bqrcskpw.fsf@junk.nocrew.org>
"Juanjo" <·····················@googlemail.com> writes:
>> (function-lambda-expression #'foo)
> (SI:LAMBDA-BLOCK FOO (A B) (+ A B))
> NIL
> FOO
> Notice that SI:LAMBDA-BLOCK is a macro proper to ECL that expands to
> something like (lambda (a b) (block foo (+ a b))).
But the standard says that the primary value of
function-lambda-expression should be a lambda expression.
Lars Brinkhoff schrieb:
> "Juanjo" <·····················@googlemail.com> writes:
> >> (function-lambda-expression #'foo)
> > (SI:LAMBDA-BLOCK FOO (A B) (+ A B))
> > NIL
> > FOO
> > Notice that SI:LAMBDA-BLOCK is a macro proper to ECL that expands to
> > something like (lambda (a b) (block foo (+ a b))).
>
> But the standard says that the primary value of
> function-lambda-expression should be a lambda expression.
Ooops, you're right. Well, in ECL this is a valid argument to COMPILE
or FUNCTION that's probably why it passed the tests without notice....
Going back to the mine to fix this....
Jj
····@rpw3.org (Rob Warnock) writes:
> Tim X <····@nospam.dev.null> wrote:
> +---------------
> | ····@rpw3.org (Rob Warnock) writes:
> | > Or Tcl?
> |
> | compiled Tcl?
> +---------------
>
> Dunno, sorry. I've never [knowingly] used compiled Tcl.
> Mostly I just use the fact the it stores procedure arglists
> and bodies where they can be recovered/printed, e.g.:
>
> tcl>proc foo {a b} {
> =># "FOO A B" adds A & B and returns the sum.
> =>expr $a + $b
> =>}
> tcl>foo 12 34
> 46
> tcl>
>
> Then, later:
>
> tcl>info args foo
> a b
> tcl>info body foo
>
> # "FOO A B" adds A & B and returns the sum.
> expr $a + $b
>
> tcl>
>
> But for a more formal docstring-only retrieval system, you
> might want something like this <http://wiki.tcl.tk/10793>.
>
Actually, Tcl/Tk wa my first non-shell scripting language (i.e. not
bash, csh, tcsh etc).
I quite like Tcl for some things. It has some interesting properties
like the one yo pointed out and others, such as easily being able to
send commands from one Tcl script too another by calling procedures in
the second script and I think it handles a list data structure better
than languages like Perl.
In fact, Tcl sort of led me to lisp. I started doing some scripts
which used lists of regular expressions to process data files, but in
some cases the data files were themselves these lists - sort of a poor
mans code as data as code idea. However, some things were hard to
achieve and then a friend pointed out that the things I was trying to
do in Tcl were pretty much native and more natural and powerful in a
lisp style language.
The cruel irony here is that I've had a lot more success convincing
people to use Tcl than lisp - I guess its because Tcl hasn't got the
wealth of built up prejudice lisp seems to have.
Maybe we could get more Cl out there by just not using the L word.
Yes, I plan to implement this in (Alegro|LW|CMUCL|ECL|GCL).
Oh, I've not heard of that, is it new - like Java or Python?
Its much more powerful than Java or Python - Paul Graeme wrote the
software he sold to Yahoo for squillions using it. Peter Siebel had a
best seller book on it recently that scored really well in amazon's
top tech books. In fact, Amazon used it quite extensively and a funny
little fellow called Kenny did some work in it which the Pythonistas
have grabbed with both hands (they killed kenny).
Oh, it must be good then. As long as its not one of those old dead
languages.
Certainly not, its very much alive.
By the time the pointy haired boss has worked it out (if he ever
does), it will be too late and they will be successful despite it
Tim
--
tcross (at) rapttech dot com dot au
Tim X <····@nospam.dev.null> wrote:
+---------------
| ····@rpw3.org (Rob Warnock) writes:
| > Dunno, sorry. I've never [knowingly] used compiled Tcl.
...
| In fact, Tcl sort of led me to lisp. I started doing some scripts
| which used lists of regular expressions to process data files, but in
| some cases the data files were themselves these lists - sort of a poor
| mans code as data as code idea. However, some things were hard to
| achieve and then a friend pointed out that the things I was trying to
| do in Tcl were pretty much native and more natural and powerful in a
| lisp style language.
+---------------
Tcl sort of led me to Lisp, too, but not for the reasons you cite.
I was doing user-mode hardware development/debugging using TCL as
a base, with a ".so" of application-specific C code bolted on the
side ["mmap()", "mpin()", "peek()", "poke()", etc.], which Tcl
supports quite nicely. But when I wrote 'scope loops[1] in Tcl
they were *so* sloooowwww that I had turn turn off the lights
to see the triggered traces on the oscilloscope.
A friend suggested using Scheme, which he said had "real data types,
not just strings". So I switched to SCM, with a similar ".so" bolt-on.
*Way* faster! I later switched again to MzScheme [faster still, plus
numerous extensions/libraries], and finally a few years ago to CMUCL,
which had the advantages that: (1) I didn't need my bolt-on ".so", I
could write everything I needed directly in CMUCL [albeit using calls
to "internal" routines like SYSTEM:INT-SAP & SYSTEM:SAP-REF-32]; and
(2) small 'scope loops in compiled CMUCL ran at the same speed C did!!
So I've been using CMUCL for user-mode hardware development ever since...
+---------------
| The cruel irony here is that I've had a lot more success convincing
| people to use Tcl than lisp - I guess its because Tcl hasn't got the
| wealth of built up prejudice lisp seems to have.
+---------------
See my previous postings re "OPFR", my "Outer-Parentheses-Free REPL",
which -- if you predefine almost all the things users will need to
do as functions (a.k.a. "commands") -- looks a lot to users like Tcl
at first glance... until they have to do something with subexpressions:
opfr> deflex foo "abcde"
FOO
opfr> subseq foo 2 4
"cd"
opfr> char foo 3
#\d
opfr> setf (char foo 3) #\D
#\D
opfr> format t "Foo is now: \"~a\"~%" foo
Foo is now: "abcDe"
NIL
opfr>
It's quite surprising how much the acceptance of the interface
goes up when *all* you do is remove the outer two parens! ;-} ;-}
-Rob
-----
Rob Warnock <····@rpw3.org>
627 26th Avenue <URL:http://rpw3.org/>
San Mateo, CA 94403 (650)572-2607
Oops! I just wrote this:
+---------------
| ... But when I wrote 'scope loops[1] in Tcl
| they were *so* sloooowwww that I had turn turn off the lights
| to see the triggered traces on the oscilloscope.
+---------------
But forgot to supply the footnote:
[1] A "'scope loop" or "oscilloscope loop" is a (usually short)
piece of code that pokes at the hardware in such a way that
you can synchronize the trace of an oscilloscope to its effect,
and then observe [on the 'scope] the response to the poking
the loop gave it. A frequent useful loop at the very beginning
of bringing up a new piece of hardware is:
(loop until (listen) do
(reset-hardware) ; Poke, then release, the RESET# wire
(dotimes (i SOME-NUMBER)) ; Increase this as you debug further
(trigger-scope) ; By POKE'ing some other location
(sleep 0.001)) ; [Or larger, as suits]
-Rob
-----
Rob Warnock <····@rpw3.org>
627 26th Avenue <URL:http://rpw3.org/>
San Mateo, CA 94403 (650)572-2607
From: David Steuber
Subject: Re: Theories on why Lisp source *seems* to have less comments?
Date:
Message-ID: <871ws5xdtu.fsf@david-steuber.com>
Oddly enough, I found Perl to be a decent stepping stone to Lisp.
--
The lithobraker. Zero distance stops at any speed.
This post uses 100% post consumer electrons and 100% virgin photons.
At 2.6 miles per minute, you don't really have time to get bored.
--- Pete Roehling on rec.motorcycles
From: Dmitry Gorbatovsky
Subject: Re: Theories on why Lisp source *seems* to have less comments?
Date:
Message-ID: <e9uihk$5sf$1@nntp.aioe.org>
Jonathon McKitrick wrote:
> I've found this to be the case in much of the code I've read.
> Here are my theories on why:
>
> 1. Lisp programmers are too busy solving complex problems to document
> their code.
> 2. Lisp is so powerful it makes programmers lazy, so why waste
> keystrokes?
> 3. Lisp is more readable, so is more self-documenting.
> 4. With docstrings, who needs comments?
> 5. It's too hard to type in English after using s-expressions for so
> long.
>
> What do you all think? Any additions?
The whole idea, i believe, is precisely and consistently express oneself
"way of something" to the "computer".
So it seems only natural for programming language to facilitate a
human-computer interaction in a way that doesn't appeal for comments on
another language.
Maybe we may differentiate betwin "machine oriented" and "human oriented"
programming languages.
dg
And of course :
"Programs must be written for people to read, and only incidentally
for machines to execute."
-- Abelson & Sussman, SICP (preface to the first edition)
Jonathon McKitrick wrote:
> Suppose you have (as I do) an application that generates multi-page pdf
> reports. How the heck do you write a test suite for this?
Among other things, you should write unit tests for subsections of
the code. Try to achieve 100% branch coverage with these tests.
I use Waters' RT and COVER packages when I do this, although COVER
doesn't deal with CLOS all that well.
Paul
Paul F. Dietz wrote:
> Jonathon McKitrick wrote:
>
> > Suppose you have (as I do) an application that generates multi-page pdf
> > reports. How the heck do you write a test suite for this?
>
> Among other things, you should write unit tests for subsections of
> the code. Try to achieve 100% branch coverage with these tests.
> I use Waters' RT and COVER packages when I do this, although COVER
> doesn't deal with CLOS all that well.
My google-fu isn't working for me. Where can I find out about these
packages?
>
> Paul
Nathan Baum <···········@btinternet.com> wrote:
> Paul F. Dietz wrote:
> > Jonathon McKitrick wrote:
> >
> > > Suppose you have (as I do) an application that generates multi-page pdf
> > > reports. How the heck do you write a test suite for this?
> >
> > Among other things, you should write unit tests for subsections of
> > the code. Try to achieve 100% branch coverage with these tests.
> > I use Waters' RT and COVER packages when I do this, although COVER
> > doesn't deal with CLOS all that well.
>
> My google-fu isn't working for me. Where can I find out about these
> packages?
>
For COVER:
http://www.cs.cmu.edu/afs/cs/project/ai-repository/ai/lang/lisp/code/tes
ting/cover/0.html
On 2006-07-23 22:50:04 -0400, "Nathan Baum" <···········@btinternet.com> said:
> My google-fu isn't working for me. Where can I find out about these
> packages?
rt can be found at: <http://www.cl-user.net/asp/libs/cl-rt>
Both are from a paper by Richard Waters which contains the full source
of cover as well:
<http://www.merl.com/reports/docs/TR91-04.pdf>
Raffael Cavallaro wrote:
> On 2006-07-23 22:50:04 -0400, "Nathan Baum" <···········@btinternet.com> said:
>
> > My google-fu isn't working for me. Where can I find out about these
> > packages?
>
> rt can be found at: <http://www.cl-user.net/asp/libs/cl-rt>
>
> Both are from a paper by Richard Waters which contains the full source
> of cover as well:
>
> <http://www.merl.com/reports/docs/TR91-04.pdf>
Excellent. Thank you kindly.
Nathan Baum wrote:
> Paul F. Dietz wrote:
>
>>Jonathon McKitrick wrote:
>>
>>
>>>Suppose you have (as I do) an application that generates multi-page pdf
>>>reports. How the heck do you write a test suite for this?
>>
>>Among other things, you should write unit tests for subsections of
>>the code. Try to achieve 100% branch coverage with these tests.
>>I use Waters' RT and COVER packages when I do this, although COVER
>>doesn't deal with CLOS all that well.
>
>
> My google-fu isn't working for me. Where can I find out about these
> packages?
In addition to the canonical links others gave, there are hacked copies
of RT in SBCL and in GCL ansi-tests. It would probably be a good idea
to think about bringing both RT and COVER up to date.
I have a project on my to-do list to rewrite COVER so the actions at
run time can be extended. One thing I want to use this for is to provide
feedback for automated test generation.
BTW, papers I've seen suggest good unit testing will eliminate about
half the user-visible defects that would otherwise escape system
testing. YMMV.
Paul
Nathan Baum wrote:
> Paul F. Dietz wrote:
> > Among other things, you should write unit tests for subsections of
> > the code. Try to achieve 100% branch coverage with these tests.
> > I use Waters' RT and COVER packages when I do this, although COVER
> > doesn't deal with CLOS all that well.
>
> My google-fu isn't working for me. Where can I find out about these
> packages?
Overview of test frameworks:
http://wiki.alu.org/Test_Frameworks
Tayssir
From: Pascal Costanza
Subject: Re: On writing test cases... (was Lisp comments)
Date:
Message-ID: <4iik51F3p2r9U1@individual.net>
Jonathon McKitrick wrote:
> Suppose you have (as I do) an application that generates multi-page pdf
> reports. How the heck do you write a test suite for this?
Develop a version of your software that produces pdf files that you
manually check for correctness. If you're done, take a snapshot of the
generated pdf files in one folder as the expected results. The test
suite then consists of generating pdf files and performing a binary
comparison of the two folders. Thus, you will notice after changes to
your code whether the contents of the pdf files are affected or not.
Nobody promised you it's easy... ;)
Pascal
--
My website: http://p-cos.net
Closer to MOP & ContextL:
http://common-lisp.net/project/closer/
Pascal Costanza wrote:
> Jonathon McKitrick wrote:
> > Suppose you have (as I do) an application that generates multi-page pdf
> > reports. How the heck do you write a test suite for this?
>
> Develop a version of your software that produces pdf files that you
> manually check for correctness. If you're done, take a snapshot of the
> generated pdf files in one folder as the expected results. The test
> suite then consists of generating pdf files and performing a binary
> comparison of the two folders. Thus, you will notice after changes to
> your code whether the contents of the pdf files are affected or not.
Additionally, in as much as test suites are an alternative to comments,
they only document what they test. Writing a test suite for an entire
program is basically writing a single comment for an entire program:
not terribly useful.
Instead, one would write tests for the components of the report
generator. Without knowing what your reports are like, it's hard to say
what those components are.
And of course, certain creative elements can't be tested automatically.
You can test the factual elements of your generated reports, but you
can't automatically test if it looks nice.
>
> Nobody promised you it's easy... ;)
>
>
> Pascal
>
> --
> My website: http://p-cos.net
> Closer to MOP & ContextL:
> http://common-lisp.net/project/closer/
Jonathon McKitrick wrote:
> I've found this to be the case in much of the code I've read.
> Here are my theories on why:
>
> 1. Lisp programmers are too busy solving complex problems to document
> their code.
0.8. Many programmers don't value comments, or clear communication to
other programmers. Lisp or no Lisp.
0.9. Lisp is less often seen in industrial production, where comments
are more likely to be mandated or evolve from necessity.
The Chicken Scheme sources are not much commented. However, they're
well organized and not too difficult to figure out. I think my own
CMake build is fairly verbose with comments, but I wonder if a person
who doesn't know CMake would agree with me. Comments are partly a
matter of perspective. You perceive your own code to be clearer than
it is.
I do think the level of commenting is an artifact of the individual
programmer.
Cheers,
Brandon Van Every