Time to encourage meaningful type parameter names? Discuss

Yet another thread that probably belongs on scala-debate.

AND to answer with my opinion :  I think using meaningful type parameter names can make sense, but there's a balance to be had.

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.
OK, that's it. Discuss :-)

Thanks,Ken

Yet another thread that probably belongs on scala-debate.

AND to answer with my opinion :  I think using meaningful type parameter names can make sense, but there's a balance to be had.

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.
OK, that's it. Discuss :-)

Thanks,Ken

On 16/11/2011 19:53, Ken McDonald wrote:
> OK, that's it. Discuss :-)

Aren't this kind of thread, and the others you started, belonging more to scala-debate?
scala-user description states it is about "questions and discussions about the Scala
programming" (mm, is there an extra "the" or a missing "language"? the meaning isn't the
same...)
scala-debate is about "questions and suggestions around the future of Scala" among others.

In fact, most of these discussions end to scala-debate, but often late.

Perhaps I am too picky about these questions, maybe because I am moderator in some
forums... :-)

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