From: Arne Babenhauserheide <arne_bab@web.de>
To: Mark H Weaver <mhw@netris.org>
Cc: guile-user@gnu.org
Subject: Re: Python-style doctests in Guile (implemented, please comment)
Date: Mon, 31 Jul 2017 19:23:36 +0200 [thread overview]
Message-ID: <871sowmri4.fsf@web.de> (raw)
In-Reply-To: <87ini8zs4w.fsf@netris.org>
[-- Attachment #1: Type: text/plain, Size: 3166 bytes --]
Hi Mark,
String-literals are a problem I did hit, and I’d be happy to lose that
problem without losing the ease of starting a procedure with tests which
double as automatically verified documentation.
Mark H Weaver <mhw@netris.org> writes:
>> (import (examples doctests))
>>
>> (define (one)
>> "(test 'foo
>> (test-equal 1 (one)))"
>> 1)
>
> While it may sometimes be beneficial to include a few
> examples in the documentation, a full test suite does not, IMO, belong
> in the doc string.
I think there’s a misconception here: These doctests are not intended to
replace a full test suite. They provide simple tests which double as
automatically verified documentation.
This is why I asked whether what I implemented is too complex (by
providing all of srfi-64 here). If you get clear benefits from
editor-support, the test is typically too complex for a doctest.
However editor-support could be provided as it is for org-mode: By
editing the region in a specialized sub-buffer.
The tests here are first-of-all intended for humans to read.
Why does code in string-literals bring a loss of hygiene? I’s read in
the module as if it had been written directly in a lambda and read
during parsing. Am I missing something or are you envisioning mutation
of the string prior to reading and evaluating it?
Panicz Maciej Godek <godek.maciek@gmail.com> writes:
> I agree with Mark, that putting tests inside a string in Lisp is a
> terrible idea, because Lisp doesn't have Python's shortcommings,
…
> There is no point in trading something better for something worse merely
> because people from Python (or elsewhere) can't afford this "better".
This doesn’t correctly represent the situation of Python. It is
perfectly possible in Python to write tests in literal code — for
example by using attributes of a function to hold functions which run
the tests.
What doctests provide is a way to write example usage first and foremost
for humans, directly at the top of the function definition, and have it
checked automatically to ensure that these examples in auto-generated
documentation actually work and keep working.
Using a define-with-tests (or define-with-examples) does not allow
writing for humans first, so it does not reach feature-parity. I could
use pretty-print to create an examples section of the documentation, but
I won’t know how it is going to be formatted while writing the code.
(though this need not be a pure drawback)
This is why I’m looking into doctests in the first place. If you have
something which provides feature parity, I’m all for using that
instead. Requirements:
- Can be verified automatically.
- Becomes part of auto-generated documentation.
- Is "physically" close to the definition of the procedure (same file,
no other definitions between the tests/examples and the procedure).
Ideally it should look like what I’d run in the REPL to use the
procedure, but I don’t think that this must be a hard requirement.
Best wishes,
Arne
--
Unpolitisch sein
heißt politisch sein
ohne es zu merken
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]
next prev parent reply other threads:[~2017-07-31 17:23 UTC|newest]
Thread overview: 11+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-07-30 18:54 Python-style doctests in Guile (implemented, please comment) Arne Babenhauserheide
2017-07-31 8:22 ` Chaos Eternal
2017-07-31 17:44 ` Arne Babenhauserheide
2017-08-01 1:36 ` Chaos Eternal
2017-07-31 12:51 ` Mark H Weaver
2017-07-31 13:04 ` Panicz Maciej Godek
2017-07-31 17:23 ` Arne Babenhauserheide [this message]
2017-08-01 22:04 ` Vítor De Araújo
2017-10-10 18:21 ` Arne Babenhauserheide
2017-10-10 22:40 ` Vítor De Araújo
2017-10-14 13:05 ` Arne Babenhauserheide
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/guile/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=871sowmri4.fsf@web.de \
--to=arne_bab@web.de \
--cc=guile-user@gnu.org \
--cc=mhw@netris.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).