+1
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.
Sytef
> 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/
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 <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."
