Re: [ANN] SmalltalkTypes 1.2

Bob Nemec wrote:

> ...
> So it's only the arguments that are scanned, not the local method and block
> variables (list index each)?  ... that's why I was wondering about the
> 'argument, local, block' variable naming convention.

Yes you are right. While it may be useful to use a similar
naming convention for local variables, it is not the aim of
SmalltalkTypes to suggest how you should write the implementation
of your methods.

The STTs convention aims to make it possible to unambiguously
declare - with minimum effort - what your method *expects*
from  its callers, and what it *promises* in return if the
callers keep their part of the deal.

If you tell other programmers your code follows  "STTs",
you are basically saying:

"If you call my method with the indicated types of arguments,
it will return an object of the indicated type. If you call
it with other types of arguments, it may still be useful
to you, but I can't make any guarantees about it".

In statically typed languages like C++/Java, it is hard to
"lie about your types", because the compiler enforces them.
The idea of STTs is to give programmers the freedom and
*responsibility* to break or follow the rules as needed,
yet give them a language for declaring them.

It's hard to break rules if you have no means for defining them.
And if you don't have an economic way of expressing the contracts,
most people won't bother.



> Is it correct to say that you're 'publishing' the SmalltalkTypes interface,
> not checking to see if the correct type is used when sending a method.
> i.e. if #anotherMethodOn: was defined as 'anotherMethodOn: aDate', I'm
> assuming you would not check the sending method for a valid 'aDate'
> argument.

Yes. What happens *inside* a method is not part of the 'contract'.

You may or may not decide to create an 'assert' inside your
method to ensure the method is indeed called with correct
arguments.  But the basic philosphy is that you *need not
care* if someone calls your method with wrong types of arguments.

You give them the freedom to do so, on their own risk -
just because you are able to precisely point out to them
which usage-scenarios are under their own risk.

Perhaps they use it 'wrongly' for a good reason and benefit
from doing so.  But you only care that you are able to exactly
state the promise *you* make about your method.

Why? Because people are more likely to buy your class library
when some specific, unambiguous, promises can be made about it.
It adds value to your software if you can more precisely specify
how it behaves when used in connection with other software.

STTs is very close in spirit to Contract-based-programming, but
in a sense where the contract holds between responsible humans,
not between text segments called source-code.

Panu Viljamaa

--
http://members.fcc.net/panu/SmalltalkTypes.htm

> .............
> The STTs convention aims to make it possible to unambiguously
> declare - with minimum effort - what your method *expects*
> from  its callers, and what it *promises* in return if the
> callers keep their part of the deal.

.........
In the examples I have seen posted here, I have not seen how the return type is
specified.  Can you provide an example please?

Chris Lopeman wrote:

> .........
> In the examples I have seen posted here, I have not seen how the return type is
> specified.  Can you provide an example please?

Here's  few examples from RULE1:

    3) ^anInteger
    4) ^anInteger := 123
    5) ^anObjectClass

Thus if what follows the '^'   looks like what an argument should look like,
then the same rules apply.

You can also specify the return types with  a literal expression such as  ^ 123
or by "sending a message to a class" like:  ^ Array with: 123  .

There's only 8 rules altogether at http://members.fcc.net/panu/8rules.htm
and several of them deal  specifically with return types.

The general principle is that you should be able to 'naturally' understand
what the return type is,  if it is defined according to the rules.

-Panu Viljamaa
--
http://members.fcc.net/panu/SmalltalkTypes.htm

I dunno.  I don't really like names like 'anInteger' very much.  I'd rather see
things like:

bagNumber
orderNumber
referenceNumber

etc.

i.e., I find the code easier to follow when the names describe the object,
rather than the object's 'type'.

YMMV, of course.


In article <3CFCDEEB.ADBF35A2@fcc.net_NOSPAM>,
Panu Viljamaa  <panu@fcc.net_NOSPAM> wrote:

--
James A. Robertson
Product Manager (Smalltalk), Cincom
[hidden email]
<Talk Small and Carry a Big Class Library>

[hidden email] wrote:

> ... I don't really like names like 'anInteger' very much.  I'd rather see things
> like:
> bagNumber
> orderNumber
> referenceNumber

Thanks for the comment James, I agree

Fortunately your preference is already accommodated,
in SmalltalkTypes 1.2. 'Rule 1' is:

    <all lowercase prefix>
    <Name of an existing class>
    {optional meta 'Class' specifier}
    {optional digit}

'Number' is a class in Smalltalk, so 'orderNumber' in STTs
is unambiguously identified as carrying an object of type Number.

---
The main point of STTs is to allow us define without doubt
what it *means* in terms of programming logic that an argument
is a Number. How is this different from the argument being an
Integer? How should programmers indicate this difference in
their code?

In an early version of STTs, the rule was: "The argument
should be named as  'a<ClassName>' or 'an<ClassName>'".
Thanks to the feedback from this newsgroup, STTs now allows
*any lowercase prefix*.

The goal of STTs is really not to be the recommendation
for "Best naming conventions in Smalltalk". Rather
it is to define constraints on naming that allow the
expected type of an argument (plus return  value) be
indicated in an unambiguous, machine readable way -
without taxing the programmer with many new conventions.

-Panu Viljamaa

--
http://members.fcc.net/panu/SmalltalkTypes.htm