I love Sunit as specification validation.
I like doctest just a validated doc. I do not care that the are used as tests. This is not the main goal to me
The goal is make sure that the reader understand fast.
I like that there are in the comments because in a PharoDoc the examples woudl be there.


        > On Sep 16, 2016, at 8:37 PM, stepharo <steph...@free.fr
        <mailto:steph...@free.fr>> wrote:
        > + 1
        > Changing the language metamodel for simple validated
        comments is a huge effort for nothing.
        > Clement is good at VM level but not at other level :)

        I think there is a misunderstanding :). I do not see any
        implication to the language meta-model in the remark of Clement.

        In fact, I expressed exactly the same opinion, that the design
        of things like PythonDoc comes from the fact that those people
        do not rely on an IDE, so their design focuses on the only
        thing they have: source code. Clement remarked that we already
        have SUnit tests and he suggested that we could just enhance
        the IDE to present them next to the methods. This might
        actually be less straightforward with SUnit because it was not
        made for preserving links to the code, but it can work out of
        the box with something like GTExamples.

    Yes, the language meta-model is already too complex in Pharo IMHO,
    let's not make it even more complex. I should have precised that's
    not what I meant if this was not obvious to everyone.

    /1. Method docs with examples, so a user can see an example usage
    of a method (sunit test methods sometimes aren't good "examples")/
    /2. We already had (and still have) some method docs where the
    example code just won't work anymore because the methods or
    classes used/


    I'm suggesting to show the SUnit test code (or example code, or
    whatever) next to the method, and being able to create a unit test
    this way instead of only the existing green/red button and the
    "browse tests" entry in the right click menu. For existing methods
    having in their comment executable code to test how they work (as
    you mentioned), the code can just be moved to the test shown in
    the pane next to it (through a script discovering all cases like
    that or manually).

    The example usage would still be shown next to the code for the
    user, except it would already be under version control as existing
    SUnit tests are, it can now have syntax coloring which is not
    present in comments, it's automatically executed by each Pharo
    build through SUnit hence detecting regressions and the meta-model
    is not getting more complex at all. As Tudor said, it's only about
    IDE changes.

    I believe that some SUnit tests are sometimes not good examples
    because they're higher level tests (application tests, business
    tests) while as for python doctests it's only relevant to show
    unit tests next to the method the unit test validates. Currently I
    believe Nautilus discovers tests and add the green/red button
    based on name conventions. Foo>>bar has this feature if
    FooTests>>testBar is implemented. So it's either a matter of
    improving this heuristic or educating the community with this
    existing name convention. In any case, I don't think it's more
    changes for the user than having to learn convention in the

Yes, we should d some experiments with different solutions and see what works.

I like the simplicity of having code in comments, at the moment I don't like when we use the code highlighter, because this looks a bit confusing.

I would like a better link between methods and sunit tests, too.

I still don't think that unit tests can fully replace code examples. And having a possibility to validate the code from method comments would be nice.

For example, some time ago there were some examples in Color methods like
wheel: thisMany
"Return a collection of thisMany colors evenly spaced around the color wheel."
    "Color showColors: (Color wheel: 12)"

the method #showColors: was long gone, so I replaced the comment to use #inspect instead.

But this code example is not about validation, a unit test would look like

self assert:(Color wheel: 12) equals: {(Color r: 0.7000000000000001 g: 0.07 b: 0.07 alpha: 1.0). (Color r: 0.7000000000000001 .....}

This code example is about a simple usage: "how would Color wheel:12 look like ? Ha just inspect the result and see yourself"

And having a way to detect when the code example "Color showColors: .." doesn't work anymore because the method was
removed, or if the Code example
"(CompiledMethod compiledMethodAt: #author) author"
doesn't work anymore because the method was moved from CompiledMethod to Compiled code ;-)
would be nice.

Yes maybe we can find another way to link real example code (not code in comments) to the actual method with better tool support, but we can not cover this with unit tests style methods alone.

Even a simple example like:
'pharo' capitalized  " >>> 'Pharo'"
this reads better than
self assert:'pharo' capitalized equals:'Pharo'
Ok, it is not that bad to understand the usage of 'capitalized', its iput and output from this unit test, but not all unit tests are written like that. Some tests are mostly about testing corner cases or an implementation detail,
or other code that isn't even considered to be used outside of the test.

So, yes, we should do some more experiments and see.


        > Stef
        > Le 16/9/16 à 14:18, Denis Kudriashov a écrit :
        >> 2016-09-16 13:42 GMT+02:00 Clément Bera
        <bera.clem...@gmail.com <mailto:bera.clem...@gmail.com>>:
        >> Why don't you just change nautilus to have two text areas,
        one with the test corresponding to the method and the other
        one with the method's code ?
        >> You're saying:
        >> Their values is active documentation that can be
        automatically validated.
        >> That can also be applied to test we've already had with
        SUnit. If the only difference you want is to display the test
        next to the method, then it's an IDE problem, nothing has to
        be changed but the IDE.
        >> In python they have no other choices than putting tests in
        comments because their IDE is a text editor, they cannot
        create other panes or anything like that.
        >> It is of course true. But Stef suggestion is really much
        much simpler. It is just convention how to write examples
        inside comments. Then tools could work with them and Nicolai
        already provide simple extension for Nautilus.
        >> We already has a lot of comments with examples inside.
        Making them discoverable and testable will be nice.

        www.tudorgirba.com <http://www.tudorgirba.com>
        www.feenk.com <http://www.feenk.com>

        "Yesterday is a fact.
         Tomorrow is a possibility.
         Today is a challenge."

Reply via email to