Time to encourage meaningful type parameter names? Discuss

On Thursday 17 November 2011, Kenneth McDonald wrote:
> .... Why not require that every function name be the
> min number of characters to uniquely represent it-- ...

Please show us how to quantify "... the min number of characters
[required] to uniquely represent [every function]."

And tell us how that relates to the concept of functional abstraction.

> Ken

Randall Schulz

To be honest, I glaze over when I see the second signature but not the first.

I recommend applying the same heuristics you use for any names. The more concrete the concept, the more concrete the name should be..

Sent from my iPad

On Nov 16, 2011, at 2:18 PM, Daniel Sobral wrote:

> On Wed, Nov 16, 2011 at 16:53, Ken McDonald wrote:
>> This comes from thinking about the alleged complexity of Scala (others'
>> arguments have convinced me it is a real problem in the corporate world), my
>> own experiences as I start to penetrate a little bit of the "inner core" of
>> Scala, and most of all, trying to be productive and ask, "Are there simple
>> ways to mitigate the complexity problem?" (Assuming you believe it is a
>> problem.)
>> First, consider the following method:
>> def someMeaningfulName(x: Int, y: String, z: Long) {...}
>> I don't know about you, but I have never worked in an environment where this
>> would be considered acceptable code (unless x, y, and z actually had special
>> meaning in the problem space). I think it's a given that good software
>> engineering demands meaningful variable names, both internal and visible.
>> Now consider the following type signature:
>>
>> flatMap [B, That] (f: (A)
>> => GenTraversableOnce[B])(implicit bf: CanBuildFrom[List[A], B, That]): That
>>
>> There are three type parameters, A, B, and That. None are meaningful. Due to
>> the fortunate inclusion of f: in the type, it's fairly easy to figure out
>> the meanings of A and B. We can finally figure out the meaning of That when
>> we reach the end of the line, at which point we need to reread the entire
>> line to put everything together. (OK, you may not. I do, and I submit that
>> most programmers will need to do so once or more.)
>> In fairness, there was a valid reason for using one-char type param back
>> when type params were new; the declarations were simply (usually container
>> classes), and the one-char rule made it obvious what was a type param and
>> what was an actual type. Note the above def'n has already violated the
>> one-char rule, without really adding value.
>> How about this
>>
>> flatMap [resultElementType, resultType] (f: (inputElementType)
>> => GenTraversableOnce[resultElementType])(implicit bf: CanBuildFrom[List[inputElementType],
>> resultElementType, resultType]): resultType
>>
>> This is much more verbose, but to someone unaccustomed to Scala collections,
>> it is also much clearer. I've taken the liberty of using initial lowercase
>> to denote a parameter rather than an actual type; I believe this is illegal,
>> but I simply wanted to show how things could be made more readable.
>> If you're an experienced Scala user, this may not seem a big deal, just
>> extra characters. Consider the process of reading the type signature from
>> left to right, understanding as we go:
>> flatMap [B, That]
>>
>> vs.
>> flatMap [resultElementType, resultType]
>>
>> The second has immediate meaning. The first does not.
>> The example I chose was mid-level in complexity--it is as the top of what a
>> Scala novice should encounter, but nowhere near as complex as one might
>> encounter in Scala internals or scalaz.
>> I believe that encouraging meaninful type parameter names would help the
>> perceived "Scala complexity" problem in two ways. First, it makes the more
>> complex "beginner's" Scala signatures more immediately understandable to
>> beginners. Second, it make intellectually sophisticated Scala code more
>> acceptable to the mainstream by making it more readable.
>
> While this sounds reasonable, the more, let's say, "abstract"
> abstractions are not particularly prone to good names, because they do
> not refer to particulars.
>
> Consider, for instance a Monad[M[_]], or a method that _takes_ a monad
> "m" as argument. What is the type A of M[A] such that exists
> Monad[M[_]]? It is not the "element type", because that really works
> for collections that contains thing. If you apply it to a continuation
> monad, it doesn't make much sense. And what do you call "m" except
> "monad"?
>
> This always remind me of something that I witnessed at college. As the
> teacher explained some abstract concept in linear algebra, the class
> was very quiet. Some student then decided enough was enough and
> decided to try to get something more concrete out of the teacher. The
> dialog went pretty much like this:
>
> - Professor, I'm having trouble understanding this. Could you give as
> an example?
> - This _is_ an example.
> - No, I mean, could you give an example with numbers?
> - Oh, ok. Assume you have three numbers, a, b, and c...
>

While this sounds reasonable, the more, let's say, "abstract"
abstractions are not particularly prone to good names, because they do
not refer to particulars.

Yes, a good teacher should be able to give good examples of any
abstract concept, and the first examples shown should be as simple as
possible and contain as few extraneous complications as possible,
preferably none. Human minds are not compilers, but some teachers seem
to think they are. Our thinking tends to start in concrete terms and
progress to generalization and abstraction, not the other way around.

I recall an undergraduate class that I took many years ago in
classical control theory. The instructor would write equations and
talk about damping, natural frequency, etc. I didn't have too much
problem with it, but at least one person in particular didn't seem to
have a clue what he was talking about. She ended up getting into a
nasty spat with him. All he had to do was to give a few simple
examples and explain what the terms meant *physically*, as opposed to
*mathematically*. But apparently his mode of thinking was so abstract
that it did not occur to him.

Take a look at the IEEE Transactions on Automatic Control sometime for
some extreme examples of this kind of thinking. It tends to be very
abstract and mathematical with few practical examples of how the
concepts can be applied. Some of the authors almost seem to consider
practical applications and examples to be trivial and beneath their
dignity to spend time on -- an excercise left for the student.

--Russ P.

On Nov 16, 11:18 am, Daniel Sobral wrote:
> On Wed, Nov 16, 2011 at 16:53, Ken McDonald wrote:
> > This comes from thinking about the alleged complexity of Scala (others'
> > arguments have convinced me it is a real problem in the corporate world), my
> > own experiences as I start to penetrate a little bit of the "inner core" of
> > Scala, and most of all, trying to be productive and ask, "Are there simple
> > ways to mitigate the complexity problem?" (Assuming you believe it is a
> > problem.)
> > First, consider the following method:
> > def someMeaningfulName(x: Int, y: String, z: Long) {...}
> > I don't know about you, but I have never worked in an environment where this
> > would be considered acceptable code (unless x, y, and z actually had special
> > meaning in the problem space). I think it's a given that good software
> > engineering demands meaningful variable names, both internal and visible.
> > Now consider the following type signature:
>
> > flatMap [B, That] (f: (A)
> > => GenTraversableOnce[B])(implicit bf: CanBuildFrom[List[A], B, That]): That
>
> > There are three type parameters, A, B, and That. None are meaningful. Due to
> > the fortunate inclusion of f: in the type, it's fairly easy to figure out
> > the meanings of A and B. We can finally figure out the meaning of That when
> > we reach the end of the line, at which point we need to reread the entire
> > line to put everything together. (OK, you may not. I do, and I submit that
> > most programmers will need to do so once or more.)
> > In fairness, there was a valid reason for using one-char type param back
> > when type params were new; the declarations were simply (usually container
> > classes), and the one-char rule made it obvious what was a type param and
> > what was an actual type. Note the above def'n has already violated the
> > one-char rule, without really adding value.
> > How about this
>
> > flatMap [resultElementType, resultType] (f: (inputElementType)
> > => GenTraversableOnce[resultElementType])(implicit bf: CanBuildFrom[List[inputElementType],
> > resultElementType, resultType]): resultType
>
> > This is much more verbose, but to someone unaccustomed to Scala collections,
> > it is also much clearer. I've taken the liberty of using initial lowercase
> > to denote a parameter rather than an actual type; I believe this is illegal,
> > but I simply wanted to show how things could be made more readable.
> > If you're an experienced Scala user, this may not seem a big deal, just
> > extra characters. Consider the process of reading the type signature from
> > left to right, understanding as we go:
> >      flatMap [B, That]
>
> > vs.
> >      flatMap [resultElementType, resultType]
>
> > The second has immediate meaning. The first does not.
> > The example I chose was mid-level in complexity--it is as the top of what a
> > Scala novice should encounter, but nowhere near as complex as one might
> > encounter in Scala internals or scalaz.
> > I believe that encouraging meaninful type parameter names would help the
> > perceived "Scala complexity" problem in two ways. First, it makes the more
> > complex "beginner's" Scala signatures more immediately understandable to
> > beginners. Second, it make intellectually sophisticated Scala code more
> > acceptable to the mainstream by making it more readable.
>
> While this sounds reasonable, the more, let's say, "abstract"
> abstractions are not particularly prone to good names, because they do
> not refer to particulars.
>
> Consider, for instance a Monad[M[_]], or a method that _takes_ a monad
> "m" as argument. What is the type A of M[A] such that exists
> Monad[M[_]]? It is not the "element type", because that really works
> for collections that contains thing. If you apply it to a continuation
> monad, it doesn't make much sense. And what do you call "m" except
> "monad"?
>
> This always remind me of something that I witnessed at college. As the
> teacher explained some abstract concept in linear algebra, the class
> was very quiet. Some student then decided enough was enough and
> decided to try to get something more concrete out of the teacher. The
> dialog went pretty much like this:
>
> - Professor, I'm having trouble understanding this. Could you give as
> an example?
> - This _is_ an example.
> - No, I mean, could you give an example with numbers?
> - Oh, ok. Assume you have three numbers, a, b, and c...
>
> --
> Daniel C. Sobral
>
> I travel to the future all the time.

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Am 16.11.2011 20:12, schrieb Donald McLean:
> There is a startling improvement in the readability of your modified
> method signature.
>
> On Wed, Nov 16, 2011 at 1:53 PM, Ken McDonald wrote:
>> Now consider the following type signature:
>>
>> flatMap [B, That] (f: (A)
>> => GenTraversableOnce[B])(implicit bf: CanBuildFrom[List[A], B, That]): That
>>
>> How about this
>>
>> flatMap [resultElementType, resultType] (f: (inputElementType)
>> => GenTraversableOnce[resultElementType])(implicit bf: CanBuildFrom[List[inputElementType],
>> resultElementType, resultType]): resultType
>>
>

So the resultType is a collection, a wrapper, some meta-type, we focus
on, but we could as well focus on the first param:

flatMap [OType, OWrapper] (f: (IType) => GenTraversableOnce [OType])
(implicit bf: CanBuildFrom [List [IType], OType, OWrapper]): OWrapper

is I/O common enough to be used for IN and OUT parameters? Since those
param types are always types, the word `type` is a bit of a redundancy,
isn't it? Let's try dropping it:

flatMap [O, OWrapper] (f: (I) => GenTraversableOnce [O])
(implicit bf: CanBuildFrom [List [I], O, OWrapper]): OWrapper

reversing the initial step, it would look like this (OE:= OutElement):

flatMap [OE, O] (f: (I) => GenTraversableOnce [OE])
(implicit bf: CanBuildFrom [List [I], OE, O]): O

The question is, which abbreviation is strong enough to be identified
easily, and used often enough to get used to it. By now, I learned
following conventions:

* T: used for Type in its abstract beauty, very useful if there is only
one type parameter.
* M: the almighty Monad or something, the Monad deals with
* A, B, C, ...: Actors in the order of their appearance.

I think some conventions might help, but meanwhile I prefer short - very
short - names for type parameters, because I'm a bit used to it. If I
see Some[A, B, That, C], I immediately suspect A, B and C to be
Type-Parameters, but `That` not so much. `That` ist nearly as
informative as `Something` or `Yaknow` - isn't it?

And I think there is no silver bullet naming scheme. In some context, I
and O might have strong associations coupled with them, so that they get
confusing there.