[Cuis] Fwd: Re: DIRECT version number
Peter van Rooijen
peter at aba-instituut.nl
Wed Aug 5 10:50:12 CDT 2015
Thanks Phil for the explanation.
Cheers, Peter
On Tue, Aug 4, 2015 at 5:20 AM, Phil (list) <pbpublist at gmail.com> wrote:
> 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
>
>
>
> _______________________________________________
> Cuis mailing list
> Cuis at jvuletich.org
> http://jvuletich.org/mailman/listinfo/cuis_jvuletich.org
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://jvuletich.org/pipermail/cuis_jvuletich.org/attachments/20150805/81e6c93d/attachment-0004.html>
More information about the Cuis
mailing list