Re: [Caml-list] Preferred layout for new packages

[Philippe Veber <philippe.veber@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 3175 bytes --]

 I think it's critical here to distinguish two purposes:
1. providing (compiler-checked) examples of a function for documentation
2. writing tests to check a module's functions seriously.

Putting test code in comments is a very nice way to achieve (1), but a
terrible way to achieve (2). In a documentation you want to illustrate the
use of your function, but writing a test for the function is not the most
direct, hence the most intelligible way to do so. Writing a test and an
example are two different things and you may confuse a user when putting
the former instead of the latter in your documentation. So I'd say code
extraction from documentation is very nice, only if it serves the purpose
of the documentation (of course the extraction enables to check the
examples, which is a nice feature).

Your mlt proposal seems to me a very nice way to organize test code (in the
second sense), as it emphasizes through the file extensions the following
holy trinity: specification, implementation and tests. Up to now, I would
write a separate directory with tests (written with oUnit), but now with
your suggestion in mind, it really feels wrong to do things that way.

Maybe the only limitation of your approach is that the test modules have to
respect the dependencies between the library modules: if A uses B then your
tests in B cannot use values in A. But I don't think it matters much, as
we're talking about unit test here.

Thanks for this proposal, I will definitely give it a try!

ph.




2012/11/14 forum@x9c.fr <forum@x9c.fr>

>
> Le 14 nov. 2012 à 18:00, Marek Kubica a écrit :
>
> > On Wed, 14 Nov 2012 09:42:09 -0500
> > Edgar Friendly <thelema314@gmail.com> wrote:
> >
> >> (…)
> >
> > I actually like test extraction frameworks, tools like nose and py.test
> > have made writing tests with Python much nicer, that's why I'm somehow
> > unimpressed how verbose OUnit is. But having the test code in a comment
> > seems ugly to me. Maybe there could be some CamlP4 hack to exclude it
> > on normal compilation?
>
> Being not found of extraction myself, I made another proposal in the
> latest revision of Kaputt: instead of using mli/ml file couples, I tend to
> now use mli/ml/mlt file triples. In this setting, the mlt file simply
> contains
> the code related to tests. Then, at compilation a small camlp4 preprocessor
> concatenates the contents of ml and mlt files before actual compilation.
>
> My understanding is that it reconciles two antagonistic goals:
>   - separate application code from test code;
>   - allow test code to access unexported elements.
>
> I would be glad to hear what people think of this scheme, independently
> of the Kaputt library itself (which I am not advertising here). One can
> read
> more in section 3.3 of the manual available at:
>     http://kaputt.x9c.fr/downloads.html
>
>
> Regards,
>
> Xavier Clerc
>
> --
> Caml-list mailing list.  Subscription management and archives:
> https://sympa.inria.fr/sympa/arc/caml-list
> Beginner's list: http://groups.yahoo.com/group/ocaml_beginners
> Bug reports: http://caml.inria.fr/bin/caml-bugs
>

[-- Attachment #2: Type: text/html, Size: 4032 bytes --]