[Cuis] Fwd: Re: DIRECT version number

Phil (list) pbpublist at gmail.com
Mon Aug 3 22:20:03 CDT 2015 

On Mon, 2015-08-03 at 22:35 +0200, Peter van Rooijen wrote:
> Hi,
> 
> 
> 1. I'm totally against introducing pragma's (perhaps they already
> exist in Cuis, I don't know).
> 

Too late, they're already there (VM functionality)

> 
> First of all because they are not Smalltalk, and second because they
> are not needed.
> 
> 
> What would be wrong with simply introducing a convention and adding a
> method cuisPublicSelectors to a class?
> 
> 
> To avoid seeing them on the instance side, there could also be
> cuisPublicInstanceSelectors and cuisPublicClassSelectors on the class
> side.
> 
> 
> At the top these would be defined as self allSelectors.
> 
> 
> If someone wanted to view only the public selectors in a browser, they
> would check the checkbox for that and the browser would hide the
> non-public selectors.
> 
> 
> Or the browser could show a nice public interface report added to the
> class comment.
> 
> 
> 2. On another point: interfaces such as indexable could simply be
> described by creating a class CuisInterfaceSpecification which gets a
> subclass for each interface specified. The methods belonging to the
> interface are defined and get a comment explaining the semantics of
> the method. This makes it easy for tools to check which interfaces are
> (probably) implemented by a class. If desired, each method could be
> additionally defined to return a MethodSpecification object that knows
> about preconditions, invariants, return values, argument and return
> types/interfaces...but then it becomes progressively more complicated.
> 
> 
> But anyway, in this way whoever thinks it's important enough, can add
> the info (for public selectors of a class or for whole interface
> specifications) without anyone who is not interested in that needing
> to know or care about that.
> 

This is too complicated for what I think we're trying to achieve...

> 
> In my mind that gels well with Cuis' philosophy of simplicity. But I
> could be missing the whole point...
> 

The intent (what I was going for at least) is to provide a means for
Juan and anyone else modifying the core image / packages to have a
bidirectional communications channel with anyone looking to have a
stable set of APIs that they can depend on.  It needs to be something
that's simple and easy for both Juan and us to use, or it won't get
used.  I think that Juan's pragma approach accomplishes this.  All it
signals is that 'this method will keep working as it currently does
until/unless it is formally decided to change it'.

So here's an example of how this might work:
1) Let's say we propose that #asString as a public API and Juan agrees
that this is a useful method and should be fairly stable.
Implementations of #asString get marked with a publicAPI (or whatever
name makes sense) pragma 
2) Those of us who care can then work to ensure that our code is using
these publicAPI methods when possible.  This will also help drive out
some of our own bad behavior where we were calling things that we really
shouldn't have been.
3) Time passes and life is good :-)
4) Down the line (Cuis 5.x, 6.x... whatever) Juan decides that #asString
needs to change (who knows... unicode support... or maybe he just
decides that #asString is the wrong way to do it)  Seeing that #asString
is flagged publicAPI, he knows not to 'just do it' but rather make sure
that the change gets called out in the release notes (after some mailing
list discussion if he deems it worthwhile to do so... his call) and that
since it will likely break code to probably wait for a major release.

This also allows for deprecating things that are designated as
publicAPI... just because something is public does not mean it always
will be, just that the changes to things that are need to be
communicated more richly.  For me, the documentation aspect of it is a
nice to have secondary objective that falls out of it... getting to a
stable core is the primary objective.  (i.e. we're not documenting for
the sake of documenting)

> 
> Cheers, Peter
> 
> 
> 
> 
> 
> 
> 
> 
> 
> On Mon, Aug 3, 2015 at 9:19 PM, Phil (list) <pbpublist at gmail.com>
> wrote:
>         On Mon, 2015-08-03 at 15:49 -0300, Juan Vuletich wrote:
>         > Hi Doug,
>         >
>         > On 8/2/2015 4:04 AM, Douglas Brebner wrote:
>         > > On 19/07/2015 22:38, Phil (list) wrote:
>         > >> Ready to go... we just need to agree on how to do it
>         (pragma/method
>         > >> call/method category/method name?) Also, this is most
>         definitely
>         > >> related to the 'Canonical test cases?' thread from a few
>         months ago
>         > >> as these types of test cases / docs are part of the
>         backfill I was
>         > >> referring to.
>         > >
>         > > I vaguely recall that many years ago there was a project
>         called
>         > > SmallInterfaces that let you define public interfaces to
>         objects. (Or
>         > > something like that). Would that be a good way to document
>         the
>         > > public/private api using code?
>         > >
>         > > (sorry for being so vague but I've been awake for 24+
>         hours now)
>         >
>         > Thanks for the pointer. I took a look at it. It is quite
>         like Java
>         > interfaces. The tools are interesting. But I see several
>         downsides:
>         >
>         > - Each interface is a class. Each method in the protocol is
>         an actual
>         > method. If we use this to document all public protocols in
>         Cuis, it
>         > would mean a lot of new classes and methods.
>         > - The source code of (for example) OrderedCollection>>at:
>         would not
>         > include the information of it belonging to interface
>         "Indexable".
>         > Without additional support from tools users can't tell
>         whether a message
>         > is public protocol or not. And the base image / package
>         maintainer can't
>         > easily see he's about to change a public api.
>         >
>         > I think a method pragma, that includes the name of the
>         protocol avoids
>         > these issues and is a better choice.
>         >
>         
>         
>         I agree.  Let's keep it as simple as possible and see how far
>         that gets
>         us.
>         
>         > Cheers,
>         > Juan Vuletich
>         >
>         > _______________________________________________
>         > 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

More information about the Cuis mailing list