Naming the return value

[Raynos]

What would be a good way to say:

mongo := (uri: String, options: Object?) => client: {
   collection: (name: String) => Continuable<Collection>
}

Basically I want to give the result of the mongo function a descriptive name.

[junosuarez]

I've actually started doing exactly this on some stuff I've written. Again the driving principle is clarity. I read the : as "is of type" in my head.

Related/expanding: there are quite a few revisions that we've accumulated in some of these issue threads. I'd like to start incorporating some of this feedback and closing the issues. I'll take a crack at some of that this weekend.

[Raynos]

I don't read : as "is of type". I read it as a label for the type that comes after it. It's not saying something is of a certain type, it's simply saying this type has a readable label which should give some insight into the context in which this type is used.

uri: String and name: String are obvouisly supplying context that the first one is a mongodb://bla bla uri string and the second one is a collection name string.

I personally read name := Type as "the scoped variable is of type ". It should be noted that I don't think (uri: String, options: Object?) means function (uri, options), the labels and function argument names don't need to match.

For reference here is the full definition.

/*  mongo := (uri: String, options: Object?) => db: {
        Continuable<Db>,
        close: Continuable<void>,
        collection: (name: String) => coll: {
            Continuable<Collection>,
            find: (selector: Object, options: Object?) => cursor: {
                Continuable<Cursor>,
                toArray: Continuable<Array<Value>>,
                nextObject: Continuable<Value | null>
            },
            findAndModify: (selector: Object, sort: Array?, doc: Object?,
                options: Object?) => Continuable<Value>,
            findAndRemove: (selector: Object, sort: Array?, options: Object?)
                => Continuable<Value>
            findOne: (selector: Object, options: Object?) => Continuable<Value>,
            insert: (docs: Array<Value>, options: Object?)
                => Continuable<Array<Value>>,
            mapReduce: (map: Function, reduce: Function, options: Object?)
                => Continuable<Collection>,
            remove: (selector: Object, options: Object?)
                => Continuable<Number>,
            update: (selector: Object, doc: Object?, options: Object?)
                => Continuable<Number>
        }
    }
*/

[junosuarez]

Could you elaborate on the difference between your understanding of the semantics between := and :? I don't think I follow, except for the notion of reference you capture by "the scoped variable" of the same name.

the labels and function argument names don't need to match.

I agree, although if you're commenting an above-the-function signature, I would probably be confused if they didn't match.

[Raynos]

The name before := references a named variable in the source code. The thing before : is just a named label for purposes of human readability, it does not reference something in the source code.

I also do things like

// x := String
var x = window.whatIsThis()

to annotate complex local variables.

note I also don't use Callback<T> : (Error, T) => void. I do type Callback<T> := (Error, T) => void. This means : is just argument & return value labels as well as syntax in object literal types.

[Raynos]

Using : over :=