2016-09-19 10:33 GMT+02:00 Clément Bera <bera.clem...@gmail.com>:
> On Sat, Sep 17, 2016 at 8:18 AM, Tudor Girba <tu...@tudorgirba.com> wrote:
>
>> Hi,
>>
>> > On Sep 16, 2016, at 8:37 PM, stepharo <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*
>
> Nicolai,
>
> 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 comments/pragmas.
>
>
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.
>
>
>
>
>> Cheers,
>> Doru
>>
>>
>> > 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>:
>> >> 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
>> www.feenk.com
>>
>> "Yesterday is a fact.
>> Tomorrow is a possibility.
>> Today is a challenge."
>>
>>
>>
>>
>>
>>
>
