From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Original-To: caml-list@sympa.inria.fr Delivered-To: caml-list@sympa.inria.fr Received: from mail1-relais-roc.national.inria.fr (mail1-relais-roc.national.inria.fr [192.134.164.82]) by sympa.inria.fr (Postfix) with ESMTPS id 2E68B7EE20 for ; Thu, 15 Nov 2012 10:01:05 +0100 (CET) Received-SPF: None (mail1-smtp-roc.national.inria.fr: no sender authenticity information available from domain of philippe.veber@gmail.com) identity=pra; client-ip=209.85.160.54; receiver=mail1-smtp-roc.national.inria.fr; envelope-from="philippe.veber@gmail.com"; x-sender="philippe.veber@gmail.com"; x-conformance=sidf_compatible Received-SPF: Pass (mail1-smtp-roc.national.inria.fr: domain of philippe.veber@gmail.com designates 209.85.160.54 as permitted sender) identity=mailfrom; client-ip=209.85.160.54; receiver=mail1-smtp-roc.national.inria.fr; envelope-from="philippe.veber@gmail.com"; x-sender="philippe.veber@gmail.com"; x-conformance=sidf_compatible; x-record-type="v=spf1" Received-SPF: None (mail1-smtp-roc.national.inria.fr: no sender authenticity information available from domain of postmaster@mail-pb0-f54.google.com) identity=helo; client-ip=209.85.160.54; receiver=mail1-smtp-roc.national.inria.fr; envelope-from="philippe.veber@gmail.com"; x-sender="postmaster@mail-pb0-f54.google.com"; x-conformance=sidf_compatible X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: AvkEABaupFDRVaA2k2dsb2JhbABEsQ+JOAGIeQgjAQEBAQkJCwkUBBwHgh4BAQQBQAEbEgsBAwELBgULDQ0hIQEBEQEFAQoSBhMSh2YBAwkGC51IjDOCeIRuChknAwpZiHUBBQyLPGmGLAOUJ4FVgRyKFoMwFimEEg X-IronPort-AV: E=Sophos;i="4.83,255,1352070000"; d="scan'208";a="181598785" Received: from mail-pb0-f54.google.com ([209.85.160.54]) by mail1-smtp-roc.national.inria.fr with ESMTP/TLS/RC4-SHA; 15 Nov 2012 10:01:03 +0100 Received: by mail-pb0-f54.google.com with SMTP id wz12so1277793pbc.27 for ; Thu, 15 Nov 2012 01:01:01 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:from:date:message-id:subject:to :cc:content-type; bh=Ja+aMsHpDcoYkm4jSAHgCs+5WNOXEOtzlB4M6Acq80c=; b=fZUyBoA8FgCQc1+ef1wvoifeFp2PyroeTwky8c0DDmE4ZOgevogGW/Ul+4Huc0WKWu 5eY77eFTeXZRbcDXurxslnxkLWIrvvBwHV3vuvao7Xz2xC/uO8xyd4vQGD9bha0RYTkK kP2Ye3oHofbxsZO2VbOVHOG+xIXgQFApX3J4QcbOHI6U2czC0mJELH6JmCaGK8BnzjK2 1xxnAyFuRFIa6vktC93snug5VQPpvbptcJw18sudERZXwExRAqvPH8WZzWf6zlj3X6nM /nQ9ZQqRG6Cc9C/+W+jUBODuXGeq00KRchfCZCS4zgr9cgCeXirN7x452kwtyYMf9wyJ 8org== Received: by 10.68.189.163 with SMTP id gj3mr2591357pbc.110.1352970061182; Thu, 15 Nov 2012 01:01:01 -0800 (PST) MIME-Version: 1.0 Received: by 10.66.241.169 with HTTP; Thu, 15 Nov 2012 01:00:41 -0800 (PST) In-Reply-To: <6973F6F3-317F-46A6-A53D-8796FB33E679@x9c.fr> References: <20121114124355.7e8ca762@xivilization.net> <50A3ADC1.5090402@gmail.com> <20121114180012.68bf06df@xivilization.net> <6973F6F3-317F-46A6-A53D-8796FB33E679@x9c.fr> From: Philippe Veber Date: Thu, 15 Nov 2012 10:00:41 +0100 Message-ID: To: "forum@x9c.fr" Cc: Marek Kubica , caml-list@inria.fr Content-Type: multipart/alternative; boundary=e89a8ff1ccd2e3758d04ce84e335 X-Validation-by: philippe.veber@gmail.com Subject: Re: [Caml-list] Preferred layout for new packages --e89a8ff1ccd2e3758d04ce84e335 Content-Type: text/plain; charset=windows-1252 Content-Transfer-Encoding: quoted-printable 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 > > Le 14 nov. 2012 =E0 18:00, Marek Kubica a =E9crit : > > > On Wed, 14 Nov 2012 09:42:09 -0500 > > Edgar Friendly wrote: > > > >> (=85) > > > > 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 preprocess= or > 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 > --e89a8ff1ccd2e3758d04ce84e335 Content-Type: text/html; charset=windows-1252 Content-Transfer-Encoding: quoted-printable I think it's critical here to distinguish two purposes:
1. providin= g (compiler-checked) examples of a function for documentation
2. writing= tests to check a module's functions seriously.

Putting test cod= e in comments is a very nice way to achieve (1), but a terrible way to achi= eve (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 mos= t intelligible way to do so. Writing a test and an example are two differen= t 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 documenta= tion is very nice, only if it serves the purpose of the documentation (of c= ourse 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 follow= ing holy trinity: specification, implementation and tests. Up to now, I wou= ld 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 hav= e 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 m= uch, 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 =E0 18:00, Marek Kubica a =E9crit :

> On Wed, 14 Nov 2012 09:42:09 -0500
> Edgar Friendly <thelema314@= gmail.com> wrote:
>
>> (=85)
>
> I actually like test extraction frameworks, tools like nose and py.tes= t
> 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 commen= t
> seems ugly to me. Maybe there could be some CamlP4 hack to exclude it<= br> > on normal compilation?

Being not found of extraction myself, I made another proposal in the<= br> latest revision of Kaputt: instead of using mli/ml file couples, I tend to<= br> now use mli/ml/mlt file triples. In this setting, the mlt file simply conta= ins
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:
=A0 - separate application code from test code;
=A0 - 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 rea= d
more in section 3.3 of the manual available at:
=A0 =A0 h= ttp://kaputt.x9c.fr/downloads.html


Regards,

Xavier Clerc

--
Caml-list mailing list. =A0Subscription management and archives:
ht= tps://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

--e89a8ff1ccd2e3758d04ce84e335--