document conventions about public vs private API

[ggggggggg]

In the discussion of #1974 there seems to be an implicit consensus that accessing information via the a.b syntax is part of the "private" API, and the "public" API consists of calls like b(a). The canonical example seems to be that if a is a FloatRange object a.step is not a useful value for public purposes, where step(a) is.

Depending on how that issue is resolved the convention may change somewhat, but in either case there will be some preferred convention. That convention should be documented, and so far is not as far as I could tell. Perhaps the Types section of the manual makes sense?

[ssfrr]

I don't think that the "fields are private, methods are public" convention is particularly universal. I generally don't like trivial setter/getter functions. Part of the decision for me is where the type sits on the inheritance hierarchy. If it's a concrete type and field access feels natural then I use the direct access. If it's an abstract type I'm much more likely to define a method so that subtypes are free to implement the access as they choose. If I'm subtyping and the supertype already has an access method as part of its API, then I'd use that method and consider the referenced field to be private.

I do rather like the python convention of leading underscores for private fields (e.g. a._step). It's simple and clear.

[StefanKarpinski]

One of the things I like about the a.b overloading proposal is that you can disable a.b easily and it's clear that a..b is truly private.

[ivarne]

Wouldn't it be wildly confusing if FloatRange had fr.step and fr..step return different values. I'm starting to think that the step field should be renamed because it has a different meaning than the intuitive one. Maybe mstep or something?

[StefanKarpinski]

I don't know, I think that would be fine – the fr..step is effectively private.