[Cuis] How to find out the API of a class? was: Canonical test cases?

[Bernhard Pieber]

Hi Wolfgang,

Thanks for the quick answer. See below:

Cheers,
Bernhard

> Am 01.03.2015 um 20:45 schrieb Wolfgang Eder <edw at generalmagic.at>:
> 
> hi bernhard,
> yes i agree that b) is a practical way to do it.
> 
> the hard part imho is to work out what the api actually is.
> since it carries the expectations that it should not break/change.
> because being able to change everything is part of the fun
> of working with smalltalk.
Yes indeed. It would be great if public methods could be distinguished more easily from private ones, like in other programming languages. If I remember correctly, Squeak's convention is that all methods in categores/protocols other than private should be considered part of the API. However, I am pretty sure this is not true right now, neither in Squeak nor in Cuis. Method with names starting with pvt are still handled in a special way in Cuis, see isPvtSelector. This feature is almost unused – there are only 5 such methods – so it should probably be removed to make the system simpler.

> working in an image with everything loaded would help
> with these cases, as the code could be fixed the moment
> the change happens.
I agree this would be the best, especially for such a small community. It increases the risk to introduce unwanted dependencies between packages, though. So a tool to identify these would be most welcome. Better yet would be a runtime system which enforces these package dependencies. I chatted with Juan about this the other day. He thinks this would require VM changes to implement cleanly. Pity.

> kind regards,
> wolfgang
> 
> 
> 
>> Am 01.03.2015 um 20:08 schrieb Bernhard Pieber <bernhard at pieber.com>:
>> 
>> Hi Wolfgang,
>> 
>> Great to see you are reading this list!
>> 
>> I think your suggestion is a great one. What would be the simplest way to separate those that could possibly work?
>> 
>> I can think of:
>> a) Use different test classes with a naming convention, e.g. GnagnaApiTest versus GnagnaInternalTest
>> b) Put test methods in different protocols, e.g. API testing versus internal testing
>> 
>> b) seems simpler to me and it has the advantage that one could reuse test fixtures (setUp and tearDown).
>> 
>> What do you think?
>> 
>> Cheers,
>> Bernhard
>> 
>>> Am 22.02.2015 um 07:52 schrieb Wolfgang Eder <edw at generalmagic.at>:
>>> 
>>> hi,
>>> I believe you have an excellent point here!
>>> I believe that tests are a very valuable and fitting
>>> way of documenting an API.
>>> 
>>> And I believe that there needs to be a distinction made
>>> alone the lines of blackbox vs. whitebox testing,
>>> where the distinction is whether the internal functioning
>>> is tested or not.
>>> 
>>> Blackbox tests should test just the API, treating the code
>>> as a "black" box, meaning it does not assume or know a lot
>>> about its internal workings.
>>> 
>>> Whitebox tests should test the internal workings, and these
>>> may break, or not even compile, when refactorings or
>>> restructurings are done.
>>> 
>>> My point is, all tests need to be documented whether
>>> they are blackbox or whitebox tests, because a user of the
>>> code and tests needs to know whether the tests are
>>> testing the API or the inner workings of the code.
>>> 
>>> kind regards
>>> wolfgang
>>> 
>>> 
>>> 
>>>> Am 22.02.2015 um 01:02 schrieb Phil (list) <pbpublist at gmail.com>:
>>>> 
>>>> My code migration to Cuis 4.2 has gone from a saga to an ordeal... lots
>>>> of breakage.  As I've been going through and fixing things I am thinking
>>>> that I'm possibly going from doing some things in a broken way in
>>>> Squeak/earlier Cuis to a broken way in current Cuis simply because I
>>>> don't know what the 'correct' way is.
>>>> 
>>>> One example is related to compression: there aren't any canonical
>>>> examples of how to compress/decompress files/streams so I poke around
>>>> the classes until I get to something that works for me right now having
>>>> no idea if what I come up with will still work a few versions from now.
>>>> Another example is package loading: I've been calling CodePackageFile
>>>> installFileStream:packageName:fullName: but that no longer appears to be
>>>> the correct entry point if I want dependency checking.  While I
>>>> understand that things are subject to change, would it make sense to
>>>> have some documented, fixed entry points that would attempt to make the
>>>> most sane choices by default going forward?
>>>> 
>>>> My thought was why not use test cases to help document the preferred
>>>> (and therefore, longer term supported) way of doing things.  They could
>>>> be put in Tests-Examples or something similar and could serve double
>>>> duty in the sense that they would not only help point people in the
>>>> right direction on how to use a given class, but would also serve as a
>>>> warning/reminder to anyone wanting to make changes that these are the
>>>> core calls that need to be maintained from a code compatibility
>>>> standpoint or otherwise need to be called out when compatibility needs
>>>> to be broken.  I imagine this would be a fairly small subset of
>>>> classes/methods and not try to anticipate all the edge cases, just deal
>>>> with the most common ones.
>>>> 
>>>> Does what I'm suggesting make sense / seem worthwhile?
>>>> 
>>>> 
>>>> _______________________________________________
>>>> Cuis mailing list
>>>> Cuis at jvuletich.org
>>>> http://jvuletich.org/mailman/listinfo/cuis_jvuletich.org
>>> 
>>> _______________________________________________
>>> Cuis mailing list
>>> Cuis at jvuletich.org
>>> http://jvuletich.org/mailman/listinfo/cuis_jvuletich.org
>> 
>> 
>> _______________________________________________
>> Cuis mailing list
>> Cuis at jvuletich.org
>> http://jvuletich.org/mailman/listinfo/cuis_jvuletich.org
> 
> _______________________________________________
> Cuis mailing list
> Cuis at jvuletich.org
> http://jvuletich.org/mailman/listinfo/cuis_jvuletich.org