This page is no longer maintained — Please continue to the home page at www.scala-lang.org

Time to encourage meaningful type parameter names? Discuss

180 replies
Ken McDonald
Joined: 2011-02-13,
User offline. Last seen 42 years 45 weeks ago.
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
Donald McLean
Joined: 2009-11-11,
User offline. Last seen 2 years 48 weeks ago.
Re: Time to encourage meaningful type parameter names? Discuss

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
>

dcsobral
Joined: 2009-04-23,
User offline. Last seen 38 weeks 5 days ago.
Re: Time to encourage meaningful type parameter names? Discuss

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...

Michael Schmitz
Joined: 2011-11-01,
User offline. Last seen 42 years 45 weeks ago.
Re: Time to encourage meaningful type parameter names? Discuss

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

On Wed, Nov 16, 2011 at 10:53 AM, 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.
> OK, that's it. Discuss :-)
>
> Thanks,
> Ken
>

Dinotzar Tzar
Joined: 2011-11-16,
User offline. Last seen 42 years 45 weeks ago.
Re: Time to encourage meaningful type parameter names? Discuss
On Wed, Nov 16, 2011 at 7:53 PM, Ken McDonald <ykkenmcd [at] gmail [dot] com> 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



I find GenTraversableOnce and the implicit CanBuildFrom stuff to be the startling bits. However, along with a few examples of how flatMap is used, the mystery dissolves. Or, rather, you understand that you don't need to understand the mystery. Short (and consistent) type signatures along with a few examples of usage, that's the ticket. Long names hurt eyes.

D.
 

Russ P.
Joined: 2009-01-31,
User offline. Last seen 1 year 26 weeks ago.
Re: Time to encourage meaningful type parameter names? Discuss

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.

Ken McDonald
Joined: 2011-02-13,
User offline. Last seen 42 years 45 weeks ago.
Re: Time to encourage meaningful type parameter names? Discuss

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.

Granted. Nonetheless, this is not an argument against meaningful type parameter names _where applicable_.
Cheers,Ken
Ken McDonald
Joined: 2011-02-13,
User offline. Last seen 42 years 45 weeks ago.
Re: Time to encourage meaningful type parameter names? Discuss


On Wednesday, November 16, 2011 3:17:22 PM UTC-6, Michael Schmitz wrote:
To be honest, I glaze over when I see the second signature but not the first.


Could you be more specify: Why? Why is the second signature less readable than the first?
As always, this is a serious question, not intended to be contentious. If we can figure out why certain signatures are more readable to certain classes of people, that's and advance, Jah?
Thanks,Ken 
Ken McDonald
Joined: 2011-02-13,
User offline. Last seen 42 years 45 weeks ago.
Re: Time to encourage meaningful type parameter names? Discuss
. Long names hurt eyes.

D.

So long variable names hurt eyes?
This is a serious question. Why are long variable names good, and long type parameter names bad?
Ken 
 
 

Dean Wampler
Joined: 2008-12-26,
User offline. Last seen 42 years 45 weeks ago.
Re: Time to encourage meaningful type parameter names? Discuss

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...
>

Sciss
Joined: 2008-12-17,
User offline. Last seen 28 weeks 5 days ago.
Re: Time to encourage meaningful type parameter names? Discuss

- because they will appear repeatedly across your code when you write generic methods / traits, and it's already painful to write them in single letters
- because they should be capitalised to distinguish them from values, and hence they appear with visual contrast to class names which are also capitalized
- because they are read along with their carriers. e.g. `List[A]` obviously is a list of elements, where variable `a` has no meaning.

On 17 Nov 2011, at 01:09, Ken McDonald wrote:

> . Long names hurt eyes.
>
> D.
>
> So long variable names hurt eyes?
>
> This is a serious question. Why are long variable names good, and long type parameter names bad?
>
> Ken
>
>
>

Ken McDonald
Joined: 2011-02-13,
User offline. Last seen 42 years 45 weeks ago.
Re: Time to encourage meaningful type parameter names? Discuss
- IDEs mean you do not have to type the full name every time.- ??? I don't understand your second objection.- I think in this point you're arguing for me rather than against me. List[A] may be "obviously" bet a set of elements, but my whole point was that _as type signatures have become more complex_, the "single-char type parameter" convention has lost validity. As for variable 'a' has no meaning: Show me one example, _anywhere_ of a variable that has _no_ meaning. Maybe in Prolog, but that's arguable.
Obviously I'm in favor of meaningful type parameter names, otherwise, I wouldn't have posted the original article. Even correcting for this bias, I don't believe your counterclaims stand up to scrutiny. Please don't take this as a personal attack. I am honestly trying to understand (and possibly change) the convention that IMHO partially prevents me from understanding complex type signatures as I delve deeper into Scala.
FWIW, I believe that the cost (extra characters) of providing meaningful type parameter names is inherently very low when compared to the cost of not providing them (meaning that the reader must infer the "meaning" of a type parameter). If you do not agree with this to at least some degree, we are axiomatically in conflict. This doesn't mean I despise your position :-). I just don't see any point in wasting bandwidth on differences that are fundamentally a matter of faith, not logic.
Cheers,Ken

On Wednesday, November 16, 2011 7:13:43 PM UTC-6, Sciss wrote:
- because they will appear repeatedly across your code when you write generic methods / traits, and it's already painful to write them in single letters
- because they should be capitalised to distinguish them from values, and hence they appear with visual contrast to class names which are also capitalized
- because they are read along with their carriers. e.g. `List[A]` obviously is a list of elements, where variable `a` has no meaning.

On 17 Nov 2011, at 01:09, Ken McDonald wrote:

> . Long names hurt eyes.
>
> D.
>
> So long variable names hurt eyes?
>
> This is a serious question. Why are long variable names good, and long type parameter names bad?
>
> Ken
>  
>  
>

Sciss
Joined: 2008-12-17,
User offline. Last seen 28 weeks 5 days ago.
Re: Time to encourage meaningful type parameter names? Discuss

On 17 Nov 2011, at 03:08, Ken McDonald wrote:

> - IDEs mean you do not have to type the full name every time.

( i type variable names and type names preferably without an autocompletion popup showing. )

> - ??? I don't understand your second objection.

T Abstract Type Member
Class Class
value value

easy to distinguish.

List[List[A]] - -> List a class, A a generic type parameter -- a list of a list of elements (A). simple
List[elemType] -> woopa, gotta realize there are square brackets here and no parentheses

> - I think in this point you're arguing for me rather than against me. List[A] may be "obviously" bet a set of elements, but my whole point was that _as type signatures have become more complex_, the "single-char type parameter" convention has lost validity. As for variable 'a' has no meaning: Show me one example, _anywhere_ of a variable that has _no_ meaning. Maybe in Prolog, but that's arguable.

def add( elem: A ) // yes
def add( a: Elem ) // no

why would you juggle around inside the method body with 'a' when you can have 'elem' which is clear.

here some code i'm just writing in this moment:

trait AssocEntry[ S <: Sys[ S ], A ] extends Entry[ S ] {
def value( implicit tx: S#Tx ) : A
def append( value: A )( implicit tx: S#Tx ) : AssocEntry[ S, A ]
def prepend( value: A )( implicit tx: S#Tx ) : AssocEntry[ S, A ]
}

versus

trait AssocEntry[ system <: Sys[ system ], element ] extends Entry[ system ] {
def value( implicit tx: system#transaction ) : element
def append( value: element )( implicit tx: system#transaction ) : AssocEntry[ system, element ]
def prepend( value: element )( implicit tx: system#transaction ) : AssocEntry[ system, element ]
}

honestly, i doubt anyone wants to either read or write it this way.

best, -sciss-

Ken McDonald
Joined: 2011-02-13,
User offline. Last seen 42 years 45 weeks ago.
Re: Time to encourage meaningful type parameter names? Discuss

> - IDEs mean you do not have to type the full name every time.

( i type variable names and type names preferably without an autocompletion popup showing. )

That's your preference. I have no poll, but based on the reading I've done of these groups, the large majority of programmers use features like autocompletion. So I don't believe this is a valid object. 

> - ??? I don't understand your second objection.

T          Abstract Type Member
Class  Class
value   value

easy to distinguish.

List[List[A]]  -     -> List a class, A a generic type parameter -- a list of a list of elements (A). simple
List[elemType]  -> woopa, gotta realize there are square brackets here and no parentheses


In my original post, I believe I made clear the fact that I was using initial lowercase as a presentation convenience, and not as part of the Scala language. What (if anything) should be done to differnetiate multichar type parameter names from valid type names is open to discussion. 

> - I think in this point you're arguing for me rather than against me. List[A] may be "obviously" bet a set of elements, but my whole point was that _as type signatures have become more complex_, the "single-char type parameter" convention has lost validity. As for variable 'a' has no meaning: Show me one example, _anywhere_ of a variable that has _no_ meaning. Maybe in Prolog, but that's arguable.

def add( elem: A )    // yes
def add( a: Elem )    // no

why would you juggle around inside the method body with 'a' when you can have 'elem' which is clear.

here some code i'm just writing in this moment:

   trait AssocEntry[ S <: Sys[ S ], A ] extends Entry[ S ] {
      def value( implicit tx: S#Tx ) : A
      def append( value: A )( implicit tx: S#Tx ) : AssocEntry[ S, A ]
      def prepend( value: A )( implicit tx: S#Tx ) : AssocEntry[ S, A ]
   }

versus

   trait AssocEntry[ system <: Sys[ system ], element ] extends Entry[ system ] {
      def value( implicit tx: system#transaction ) : element
      def append( value: element )( implicit tx: system#transaction ) : AssocEntry[ system, element ]
      def prepend( value: element )( implicit tx: system#transaction ) : AssocEntry[ system, element ]
   }

honestly, i doubt anyone wants to either read or write it this way.


Wow, you couldn't be more wrong. (Don't mean to be offensive, but it's the truth.). The latter has some semantic meaning to me--not much, but some. The former has no meaning whatsoever. That's a difference of  approximately infinity :-)
I just want to emphasize how serious I am about this. As far as I'm concerned, the first presentation is gibberish. The second doesn't let me understand the system, but it leads me in an appropriate direction. That's a huge difference!
Cheers,Ken

Derek Williams 3
Joined: 2011-08-12,
User offline. Last seen 42 years 45 weeks ago.
Re: Time to encourage meaningful type parameter names? Discuss

For me it makes it harder to visualize what the signature of the method actually is. When I look at flatMap, the signature 'A => M[B]' should be easy to see, and it isn't easy for me to see it in the verbose version. I would end up being dependent on the documentation to tell me what the method does, rather then just looking at the signature.

I have the same problem with java code that uses many long method names all jumbled together.

Tony Morris 2
Joined: 2009-03-20,
User offline. Last seen 42 years 45 weeks ago.
Re: Time to encourage meaningful type parameter names? Discuss

On 11/17/2011 01:33 PM, Derek Williams wrote:
>
> For me it makes it harder to visualize what the signature of the
> method actually is. When I look at flatMap, the signature 'A => M[B]'
> should be easy to see, and it isn't easy for me to see it in the
> verbose version. I would end up being dependent on the documentation
> to tell me what the method does, rather then just looking at the
> signature.
>
> I have the same problem with java code that uses many long method
> names all jumbled together.
>

What's wrong with this? Much easier to read:

FingWhatIsComingOffDaMonadEnvironment =>
FingWhatIsAMonadEnvironment[NewFingWhatTheMonadEnvironmentIsDefinedOver]

PS: Isn't this another -debatey topic?

Matthew Pocock 3
Joined: 2010-07-30,
User offline. Last seen 42 years 45 weeks ago.
Re: Time to encourage meaningful type parameter names? Discuss


On 17 November 2011 03:21, Sciss <contact [at] sciss [dot] de> wrote:

here some code i'm just writing in this moment:

  trait AssocEntry[ S <: Sys[ S ], A ] extends Entry[ S ] {
     def value( implicit tx: S#Tx ) : A
     def append( value: A )( implicit tx: S#Tx ) : AssocEntry[ S, A ]
     def prepend( value: A )( implicit tx: S#Tx ) : AssocEntry[ S, A ]
  }

versus

  trait AssocEntry[ system <: Sys[ system ], element ] extends Entry[ system ] {
     def value( implicit tx: system#transaction ) : element
     def append( value: element )( implicit tx: system#transaction ) : AssocEntry[ system, element ]
     def prepend( value: element )( implicit tx: system#transaction ) : AssocEntry[ system, element ]
  }

honestly, i doubt anyone wants to either read or write it this way.

The 2nd version is much easier to understand at the expense of being more difficult to read. Remember, in an API, the type names are part of your documentation to other people. After reading your first version, I'm left none-the-wiser what A is. In the 2nd one, it's obvious. Given that we're dealing with systems and transactions, #Tx is understandable.
I have to say that I share the OPs experience. When I first came to scala, I found that the use of extremely generic type parameter names very confusing. They don't need to be SAs, but where it makes sense using a word rather than a letter would be a really good thing.
Matthew
 


best, -sciss-




--
Dr Matthew PocockIntegrative Bioinformatics Group, School of Computing Science, Newcastle Universitymailto: turingatemyhamster [at] gmail [dot] com gchat: turingatemyhamster [at] gmail [dot] commsn: matthew_pocock [at] yahoo [dot] co [dot] uk irc.freenode.net: drdozerskype: matthew.pococktel: (0191) 2566550mob: +447535664143
Matthew Pocock 3
Joined: 2010-07-30,
User offline. Last seen 42 years 45 weeks ago.
Re: Time to encourage meaningful type parameter names? Discuss


On 17 November 2011 05:03, Tony Morris <tonymorris [at] gmail [dot] com> wrote:
 
What's wrong with this? Much easier to read:
FingWhatIsComingOffDaMonadEnvironment =>
FingWhatIsAMonadEnvironment[NewFingWhatTheMonadEnvironmentIsDefinedOver]


Names can be too short or too long. This goes for variables, defs, classes and parametrized types. Picking strawman long-names doesn't invalidate the principle of choosing informative names.
Matthew 

--
Tony Morris
http://tmorris.net/





--
Dr Matthew PocockIntegrative Bioinformatics Group, School of Computing Science, Newcastle Universitymailto: turingatemyhamster [at] gmail [dot] com gchat: turingatemyhamster [at] gmail [dot] commsn: matthew_pocock [at] yahoo [dot] co [dot] uk irc.freenode.net: drdozerskype: matthew.pococktel: (0191) 2566550mob: +447535664143
Viktor Klang
Joined: 2008-12-17,
User offline. Last seen 1 year 27 weeks ago.
Re: Time to encourage meaningful type parameter names? Discuss
I think Tony's point wass that the higher the abstraction the less specific the name can be.

On Thu, Nov 17, 2011 at 11:48 AM, Matthew Pocock <turingatemyhamster [at] gmail [dot] com> wrote:


On 17 November 2011 05:03, Tony Morris <tonymorris [at] gmail [dot] com> wrote:
 
What's wrong with this? Much easier to read:
FingWhatIsComingOffDaMonadEnvironment =>
FingWhatIsAMonadEnvironment[NewFingWhatTheMonadEnvironmentIsDefinedOver]


Names can be too short or too long. This goes for variables, defs, classes and parametrized types. Picking strawman long-names doesn't invalidate the principle of choosing informative names.
Matthew 

--
Tony Morris
http://tmorris.net/





--
Dr Matthew PocockIntegrative Bioinformatics Group, School of Computing Science, Newcastle University mailto: turingatemyhamster [at] gmail [dot] com gchat: turingatemyhamster [at] gmail [dot] commsn: matthew_pocock [at] yahoo [dot] co [dot] uk irc.freenode.net: drdozerskype: matthew.pococktel: (0191) 2566550mob: +447535664143



--
Viktor Klang

Akka Tech LeadTypesafe - Enterprise-Grade Scala from the Experts

Twitter: @viktorklang
Chris Marshall
Joined: 2009-06-17,
User offline. Last seen 44 weeks 3 days ago.
RE: Time to encourage meaningful type parameter names? Discuss
Indeed, from the pov of a functor's Map method, A and B do not have to be the "element types" at all. For example:
  trait Functor[F[_]] { def fmap[A, B](f: Functor[A], g: A => B): F[B] }
Then:
  def Function1Functor[X] = new Functor[({type l[a]=X => a})#l] { def fmap[A, B](f: X => A, g: A => B): X => B = f andThen g }
Admittedly the collection library's map method "is not map" (as Tony says: http://stackoverflow.com/questions/1722726/is-the-scala-2-8-collections-library-a-case-of-the-longest-suicide-note-in-hist/1735694#1735694) but by tying the names of the type parameters down so specifically, it may be the case that the user misses an important abstraction
Chris

Date: Thu, 17 Nov 2011 12:12:48 +0100
Subject: Re: [scala-user] Time to encourage meaningful type parameter names? Discuss
From: viktor [dot] klang [at] gmail [dot] com
To: turingatemyhamster [at] gmail [dot] com
CC: tmorris [at] tmorris [dot] net; scala-user [at] googlegroups [dot] com

I think Tony's point wass that the higher the abstraction the less specific the name can be.

On Thu, Nov 17, 2011 at 11:48 AM, Matthew Pocock <turingatemyhamster [at] gmail [dot] com> wrote:


On 17 November 2011 05:03, Tony Morris <tonymorris [at] gmail [dot] com> wrote:
 
What's wrong with this? Much easier to read:
FingWhatIsComingOffDaMonadEnvironment =>
FingWhatIsAMonadEnvironment[NewFingWhatTheMonadEnvironmentIsDefinedOver]


Names can be too short or too long. This goes for variables, defs, classes and parametrized types. Picking strawman long-names doesn't invalidate the principle of choosing informative names.
Matthew 

--
Tony Morris
http://tmorris.net/





--
Dr Matthew PocockIntegrative Bioinformatics Group, School of Computing Science, Newcastle University mailto: turingatemyhamster [at] gmail [dot] com gchat: turingatemyhamster [at] gmail [dot] commsn: matthew_pocock [at] yahoo [dot] co [dot] uk irc.freenode.net: drdozerskype: matthew.pococktel: (0191) 2566550mob: +447535664143



--
Viktor Klang

Akka Tech LeadTypesafe - Enterprise-Grade Scala from the Experts

Twitter: @viktorklang
Philippe Lhoste
Joined: 2010-09-02,
User offline. Last seen 42 years 45 weeks ago.
Re: Time to encourage meaningful type parameter names? Discuss

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... :-)

Tony Morris 2
Joined: 2009-03-20,
User offline. Last seen 42 years 45 weeks ago.
Re: Time to encourage meaningful type parameter names? Discuss

On 17/11/11 20:48, Matthew Pocock wrote:
> On 17 November 2011 05:03, Tony Morris wrote:
>
>
>> What's wrong with this? Much easier to read:
>>
>> FingWhatIsComingOffDaMonadEnvironment =>
>> FingWhatIsAMonadEnvironment[NewFingWhatTheMonadEnvironmentIsDefinedOver]
>>
>>
> Names can be too short or too long. This goes for variables, defs, classes
> and parametrized types. Picking strawman long-names doesn't invalidate the
> principle of choosing informative names.
>
> Matthew
>
>
>> --
>> Tony Morris
>> http://tmorris.net/
>>
>>
>>
>
It is extremely important to pick meaningless names. The moment you
project meaning is the moment you start making all those mistakes that
we so often see.

Joshua.Suereth
Joined: 2008-09-02,
User offline. Last seen 32 weeks 5 days ago.
Re: 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.

On Nov 16, 2011 1:53 PM, "Ken McDonald" <ykkenmcd [at] gmail [dot] com> 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.
OK, that's it. Discuss :-)

Thanks,Ken
Matthew Pocock 3
Joined: 2010-07-30,
User offline. Last seen 42 years 45 weeks ago.
Re: Time to encourage meaningful type parameter names? Discuss
On 17 November 2011 12:11, Tony Morris <tonymorris [at] gmail [dot] com> wrote:
>
It is extremely important to pick meaningless names. The moment you
project meaning is the moment you start making all those mistakes that
we so often see.

Many times the types are not devoid of meaning. Consider:
trait Graph[A, B]
vs
trait Graph[N, E]
vs
trait Graph[Node, Edge]
vs
trait Graph[TheNodeType, TheEdgeType]
Option 3 of these is (imao) optimal, as it clearly describes what role the types play without using unnecessarily verbose names. If you're not 'projecting meaning' on these two type parameters, you're not understanding the API. I've no problem with List[A], as there's nothing much to tell users about A. In a library like scalaz, consistent use of single-letter type parameters goes a long way, but then you have things like what the default letter should be for Monad vs Monoid.
I'll bug out here, as I agree this should go to -debate until/unless it results in an agreement to go through the core libs renaming things, in which case I'd be happy to give up a 'documentation saturday' to helping rename things.
Matthew

--
Tony Morris
http://tmorris.net/





--
Dr Matthew PocockIntegrative Bioinformatics Group, School of Computing Science, Newcastle Universitymailto: turingatemyhamster [at] gmail [dot] com gchat: turingatemyhamster [at] gmail [dot] commsn: matthew_pocock [at] yahoo [dot] co [dot] uk irc.freenode.net: drdozerskype: matthew.pococktel: (0191) 2566550mob: +447535664143
Tony Morris 2
Joined: 2009-03-20,
User offline. Last seen 42 years 45 weeks ago.
Re: Time to encourage meaningful type parameter names? Discuss

On 17/11/11 22:56, Matthew Pocock wrote:
> On 17 November 2011 12:11, Tony Morris wrote:
>
>> It is extremely important to pick meaningless names. The moment you
>> project meaning is the moment you start making all those mistakes that
>> we so often see.
>>
> Many times the types are not devoid of meaning. Consider:
>
> trait Graph[A, B]
>
> vs
>
> trait Graph[N, E]
>
> vs
>
> trait Graph[Node, Edge]
>
> vs
>
> trait Graph[TheNodeType, TheEdgeType]
>
> Option 3 of these is (imao) optimal, as it clearly describes what role the
> types play without using unnecessarily verbose names. If you're not
> 'projecting meaning' on these two type parameters, you're not understanding
> the API. I've no problem with List[A], as there's nothing much to tell
> users about A. In a library like scalaz, consistent use of single-letter
> type parameters goes a long way, but then you have things like what the
> default letter should be for Monad vs Monoid.
>
> I'll bug out here, as I agree this should go to -debate until/unless it
> results in an agreement to go through the core libs renaming things, in
> which case I'd be happy to give up a 'documentation saturday' to helping
> rename things.
>
> Matthew
>
>
>> --
>> Tony Morris
>> http://tmorris.net/
>>
>>
>>
>

This is exactly the mistake I refer to. Now define your operations on
the data type. What do those operations (the important bits) say about
nodes and edges? Exactly, nothing, nothing at all -- now you're stuck in
a cognitive quagmire. Please allow me to politely decline your invitation.

Joshua.Suereth
Joined: 2008-09-02,
User offline. Last seen 32 weeks 5 days ago.
Re: 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.

On Nov 16, 2011 1:53 PM, "Ken McDonald" <ykkenmcd [at] gmail [dot] com> 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.
OK, that's it. Discuss :-)

Thanks,Ken
Matthew Pocock 3
Joined: 2010-07-30,
User offline. Last seen 42 years 45 weeks ago.
Re: Time to encourage meaningful type parameter names? Discuss
[I'm now subscribed to scala-debate - sorry if you got this twice]
On 17 November 2011 13:13, Tony Morris <tonymorris [at] gmail [dot] com> wrote:
On 17/11/11 22:56, Matthew Pocock wrote:
> trait Graph[TheNodeType, TheEdgeType]

This is exactly the mistake I refer to. Now define your operations on
the data type. What do those operations (the important bits) say about
nodes and edges?

There is no meaningful isomorphism that I can repeatedly apply to Graph[Node, Edge] to get a Graph[Edge, Node] and then apply again to get back to the original graph. The nodes and edges play distinct roles. Naming them after these roles is useful documentation for the user.  
Exactly, nothing, nothing at all

It tells me a great deal about the graph API. It doesn't tell me anything about the specific choices of concrete types for Node/Edge, but that is not what type parameter names are for. It tells me what role they play in the graph, which is what type parameter names are for.  
Viktor Klang
Joined: 2008-12-17,
User offline. Last seen 1 year 27 weeks ago.
Re: Re: Time to encourage meaningful type parameter names? Dis


On Thu, Nov 17, 2011 at 2:58 PM, Matthew Pocock <turingatemyhamster [at] gmail [dot] com> wrote:
[I'm now subscribed to scala-debate - sorry if you got this twice]
On 17 November 2011 13:13, Tony Morris <tonymorris [at] gmail [dot] com> wrote:
On 17/11/11 22:56, Matthew Pocock wrote:
> trait Graph[TheNodeType, TheEdgeType]

"The" can be dropped since it cannot be anything else.
"Type" can be dropped since it can only be a type, you don't write: "val theThingVal = new Thing"
 
trait Graph[Node, Edge] <--- Looks great to me


This is exactly the mistake I refer to. Now define your operations on
the data type. What do those operations (the important bits) say about
nodes and edges?

There is no meaningful isomorphism that I can repeatedly apply to Graph[Node, Edge] to get a Graph[Edge, Node] and then apply again to get back to the original graph. The nodes and edges play distinct roles. Naming them after these roles is useful documentation for the user.  
Exactly, nothing, nothing at all

It tells me a great deal about the graph API. It doesn't tell me anything about the specific choices of concrete types for Node/Edge, but that is not what type parameter names are for. It tells me what role they play in the graph, which is what type parameter names are for.  
Philippe Lhoste
Joined: 2010-09-02,
User offline. Last seen 42 years 45 weeks ago.
Re: Time to encourage meaningful type parameter names? Discuss

On 17/11/2011 13:51, Josh Suereth wrote:
> 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.

Yes.
When I discovered Scala, I was disconcerted, not to say "shocked", by these one-letter
type names. Looked like those old C programs where developers valued conciseness over
expressiveness. You know, lines like: if (lh->v.u.s.aux == v->u.s.info)

Then I read that's a tradition in computer science, so I get used to it...
But I still believe that some well chosen names can help.
Of course, you can put signatures like those mentioned, and be more explicit in the
documentation of the API, but indeed, that's two places to look for.

On the other hand, there can be some confusion between real types (classes, etc.) and
abstract types (those used in collections, not knowing in advance what they would be);
perhaps even potential clashes (?).
Ie. is a ResultElement (I agree with Viktor, the "Type" part is a bit redundant) a real,
application level type or some abstract type? Can I have a ResultElement class in my app.
without conflict?

Specialized APIs like Graph[Node, Edge] are more OK, I suppose. Not sure about conflicts,
again.

Matthew Pocock 3
Joined: 2010-07-30,
User offline. Last seen 42 years 45 weeks ago.
Re: Re: Time to encourage meaningful type parameter names? Disc
Hi,

On 17 November 2011 14:34, Philippe Lhoste <PhiLho [at] gmx [dot] net> wrote:
On 17/11/2011 13:51, Josh Suereth wrote:
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.

Yes.
When I discovered Scala, I was disconcerted, not to say "shocked", by these one-letter type names. Looked like those old C programs where developers valued conciseness over expressiveness. You know, lines like: if (lh->v.u.s.aux == v->u.s.info)

Same here. I'd previously done a lot of Java and a few years of Haskell. I found much of the haskell libs to be impenetrable due to single-letter (and often non-mnemonic) type names, even after quite a while working with them.  

On the other hand, there can be some confusion between real types (classes, etc.) and abstract types (those used in collections, not knowing in advance what they would be); perhaps even potential clashes (?).

Agreed. I have type parameters rendered in italic and type alases as italic+bold in intellij idea. I'm not a fan of Christmas-tree highlighting, but this seems to help. Matthew
Matthew Pocock 3
Joined: 2010-07-30,
User offline. Last seen 42 years 45 weeks ago.
Re: Re: Time to encourage meaningful type parameter names? Disc
Hi,

On 17 November 2011 14:34, Philippe Lhoste <PhiLho [at] gmx [dot] net> wrote:
On 17/11/2011 13:51, Josh Suereth wrote:
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.

Yes.
When I discovered Scala, I was disconcerted, not to say "shocked", by these one-letter type names. Looked like those old C programs where developers valued conciseness over expressiveness. You know, lines like: if (lh->v.u.s.aux == v->u.s.info)

Same here. I'd previously done a lot of Java and a few years of Haskell. I found much of the haskell libs to be impenetrable due to single-letter (and often non-mnemonic) type names, even after quite a while working with them.  

On the other hand, there can be some confusion between real types (classes, etc.) and abstract types (those used in collections, not knowing in advance what they would be); perhaps even potential clashes (?).

Agreed. I have type parameters rendered in italic and type alases as italic+bold in intellij idea. I'm not a fan of Christmas-tree highlighting, but this seems to help. Matthew
dcsobral
Joined: 2009-04-23,
User offline. Last seen 38 weeks 5 days ago.
Re: Re: Time to encourage meaningful type parameter names? Dis

2011/11/17 √iktor Ҡlang
>
>
> On Thu, Nov 17, 2011 at 2:58 PM, Matthew Pocock wrote:
>>
>> [I'm now subscribed to scala-debate - sorry if you got this twice]
>> On 17 November 2011 13:13, Tony Morris  wrote:
>>>
>>> On 17/11/11 22:56, Matthew Pocock wrote:
>>> > trait Graph[TheNodeType, TheEdgeType]
>
> "The" can be dropped since it cannot be anything else.
> "Type" can be dropped since it can only be a type, you don't write: "val theThingVal = new Thing"
>
> trait Graph[Node, Edge] <--- Looks great to me

Except you just killed Node and Edge as trait/class names. At the very
least, I'd call them ANode and AnEdge.

--
Daniel C. Sobral

I travel to the future all the time.

Viktor Klang
Joined: 2008-12-17,
User offline. Last seen 1 year 27 weeks ago.
Re: Re: Time to encourage meaningful type parameter names? Dis


2011/11/17 Daniel Sobral <dcsobral [at] gmail [dot] com>
2011/11/17 √iktor Ҡlang <viktor [dot] klang [at] gmail [dot] com>
>
>
> On Thu, Nov 17, 2011 at 2:58 PM, Matthew Pocock <turingatemyhamster [at] gmail [dot] com> wrote:
>>
>> [I'm now subscribed to scala-debate - sorry if you got this twice]
>> On 17 November 2011 13:13, Tony Morris <tonymorris [at] gmail [dot] com> wrote:
>>>
>>> On 17/11/11 22:56, Matthew Pocock wrote:
>>> > trait Graph[TheNodeType, TheEdgeType]
>
> "The" can be dropped since it cannot be anything else.
> "Type" can be dropped since it can only be a type, you don't write: "val theThingVal = new Thing"
>
> trait Graph[Node, Edge] <--- Looks great to me

Except you just killed Node and Edge as trait/class names. At the very
least, I'd call them ANode and AnEdge.

trait Graph[N/*ode*/, E/*dge*/]
 

--
Daniel C. Sobral

I travel to the future all the time.



--
Viktor Klang

Akka Tech LeadTypesafe - Enterprise-Grade Scala from the Experts

Twitter: @viktorklang
Simon Ochsenreither
Joined: 2011-07-17,
User offline. Last seen 42 years 45 weeks ago.
Re: Re: Time to encourage meaningful type parameter names? Dis
Afaik C# prefixes type parameters with T and return type parameters with R ... but they also use I as a prefix for interfaces. The last holdout of Hungarian notation?
Tom Switzer
Joined: 2011-07-19,
User offline. Last seen 42 years 45 weeks ago.
Re: Time to encourage meaningful type parameter names? Discuss
I was actually a little taken back when I first came to Scala, and saw someone recommend using A, B, .. as the type parameter names over equally short, but slightly more descriptive names (eg. N (E) for nodes (edges)). Obviously, in the case of truly generic parameters, you might as well use A, B, whatever, but if a type has a defined role, context bound, or something else, then I don't mind conveying this. Personally, I prefer Graph[N,E] over Graph[Node,Edge], though.

On Thu, Nov 17, 2011 at 7:56 AM, Matthew Pocock <turingatemyhamster [at] gmail [dot] com> wrote:
On 17 November 2011 12:11, Tony Morris <tonymorris [at] gmail [dot] com> wrote:
>
It is extremely important to pick meaningless names. The moment you
project meaning is the moment you start making all those mistakes that
we so often see.

Many times the types are not devoid of meaning. Consider:
trait Graph[A, B]
vs
trait Graph[N, E]
vs
trait Graph[Node, Edge]
vs
trait Graph[TheNodeType, TheEdgeType]
Option 3 of these is (imao) optimal, as it clearly describes what role the types play without using unnecessarily verbose names. If you're not 'projecting meaning' on these two type parameters, you're not understanding the API. I've no problem with List[A], as there's nothing much to tell users about A. In a library like scalaz, consistent use of single-letter type parameters goes a long way, but then you have things like what the default letter should be for Monad vs Monoid.
I'll bug out here, as I agree this should go to -debate until/unless it results in an agreement to go through the core libs renaming things, in which case I'd be happy to give up a 'documentation saturday' to helping rename things.
Matthew

--
Tony Morris
http://tmorris.net/





--
Dr Matthew PocockIntegrative Bioinformatics Group, School of Computing Science, Newcastle University mailto: turingatemyhamster [at] gmail [dot] com gchat: turingatemyhamster [at] gmail [dot] commsn: matthew_pocock [at] yahoo [dot] co [dot] uk irc.freenode.net: drdozerskype: matthew.pococktel: (0191) 2566550mob: +447535664143

dcsobral
Joined: 2009-04-23,
User offline. Last seen 38 weeks 5 days ago.
Re: Re: Time to encourage meaningful type parameter names? Dis

2011/11/17 √iktor Ҡlang :
>
>> > trait Graph[Node, Edge] <--- Looks great to me
>>
>> Except you just killed Node and Edge as trait/class names. At the very
>> least, I'd call them ANode and AnEdge.
>
> trait Graph[N/*ode*/, E/*dge*/]

Won't show up on Scaladoc, so what's the point? Nope, I still prefer
ANode and AnEdge. :-)

dcsobral
Joined: 2009-04-23,
User offline. Last seen 38 weeks 5 days ago.
Re: Re: Time to encourage meaningful type parameter names? Dis

On Thu, Nov 17, 2011 at 13:35, Simon Ochsenreither
wrote:
> Afaik C# prefixes type parameters with T and return type parameters with R
> ... but they also use I as a prefix for interfaces. The last holdout of
> Hungarian notation?

You should see that Uncle Bob has to say about prefixing interfaces
with I. Pretty funny! :-)

Michael Schmitz
Joined: 2011-11-01,
User offline. Last seen 42 years 45 weeks ago.
Re: Re: Time to encourage meaningful type parameter names? Dis

We already have great entries in the scaladoc about type parameters.

http://www.scala-lang.org/api/current/index.html#scala.collection.Map

Peace. Michael

2011/11/17 Daniel Sobral :
> 2011/11/17 √iktor Ҡlang :
>>
>>> > trait Graph[Node, Edge] <--- Looks great to me
>>>
>>> Except you just killed Node and Edge as trait/class names. At the very
>>> least, I'd call them ANode and AnEdge.
>>
>> trait Graph[N/*ode*/, E/*dge*/]
>
> Won't show up on Scaladoc, so what's the point? Nope, I still prefer
> ANode and AnEdge. :-)
>
> --
> Daniel C. Sobral
>
> I travel to the future all the time.
>

Matthew Pocock 3
Joined: 2010-07-30,
User offline. Last seen 42 years 45 weeks ago.
Re: Re: Time to encourage meaningful type parameter names? Dis
Yes.... Wouldn't Map[K, V] or Map[Key, Value] be more self-explanatory? Peace.

2011/11/17 Michael Schmitz <michael [at] schmitztech [dot] com>
We already have great entries in the scaladoc about type parameters.

http://www.scala-lang.org/api/current/index.html#scala.collection.Map

Peace.  Michael


2011/11/17 Daniel Sobral <dcsobral [at] gmail [dot] com>:
> 2011/11/17 √iktor Ҡlang <viktor [dot] klang [at] gmail [dot] com>:
>>
>>> > trait Graph[Node, Edge] <--- Looks great to me
>>>
>>> Except you just killed Node and Edge as trait/class names. At the very
>>> least, I'd call them ANode and AnEdge.
>>
>> trait Graph[N/*ode*/, E/*dge*/]
>
> Won't show up on Scaladoc, so what's the point? Nope, I still prefer
> ANode and AnEdge. :-)
>
> --
> Daniel C. Sobral
>
> I travel to the future all the time.
>



--
Dr Matthew PocockIntegrative Bioinformatics Group, School of Computing Science, Newcastle Universitymailto: turingatemyhamster [at] gmail [dot] com gchat: turingatemyhamster [at] gmail [dot] commsn: matthew_pocock [at] yahoo [dot] co [dot] uk irc.freenode.net: drdozerskype: matthew.pococktel: (0191) 2566550mob: +447535664143
Michael Schmitz
Joined: 2011-11-01,
User offline. Last seen 42 years 45 weeks ago.
Re: Re: Time to encourage meaningful type parameter names? Dis

Well, fair point with Map[K, V]--I'm with you there!

On Thu, Nov 17, 2011 at 10:21 AM, Matthew Pocock
wrote:
> Yes.... Wouldn't Map[K, V] or Map[Key, Value] be more self-explanatory?
> Peace.
>
> 2011/11/17 Michael Schmitz
>>
>> We already have great entries in the scaladoc about type parameters.
>>
>> http://www.scala-lang.org/api/current/index.html#scala.collection.Map
>>
>> Peace.  Michael
>>
>>
>> 2011/11/17 Daniel Sobral :
>> > 2011/11/17 √iktor Ҡlang :
>> >>
>> >>> > trait Graph[Node, Edge] <--- Looks great to me
>> >>>
>> >>> Except you just killed Node and Edge as trait/class names. At the very
>> >>> least, I'd call them ANode and AnEdge.
>> >>
>> >> trait Graph[N/*ode*/, E/*dge*/]
>> >
>> > Won't show up on Scaladoc, so what's the point? Nope, I still prefer
>> > ANode and AnEdge. :-)
>> >
>> > --
>> > Daniel C. Sobral
>> >
>> > I travel to the future all the time.
>> >
>
>
>
> --
> Dr Matthew Pocock
> Integrative Bioinformatics Group, School of Computing Science, Newcastle
> University
> mailto: turingatemyhamster [at] gmail [dot] com
> gchat: turingatemyhamster [at] gmail [dot] com
> msn: matthew_pocock [at] yahoo [dot] co [dot] uk
> irc.freenode.net: drdozer
> skype: matthew.pocock
> tel: (0191) 2566550
> mob: +447535664143
>

Alex Repain
Joined: 2010-07-27,
User offline. Last seen 1 year 31 weeks ago.
Re: Re: Time to encourage meaningful type parameter names? Dis


2011/11/17 Matthew Pocock <turingatemyhamster [at] gmail [dot] com>
Yes.... Wouldn't Map[K, V] or Map[Key, Value] be more self-explanatory? Peace.


There will always be people to not catch [K,V] as [Key, Value], and others to not catch what is Key or Value because they just don't know what a Map is (let's say the hereby example is easier than the general case). Using A,B,C and so on is a way to force the API user to know his tool, to understand it, and to RTFDocumentation - of course yes, you'd better document your code if it uses abstract {type names} or value names. As for using longer names, I'd say as stated before : if your concepts are abstract (pure mathematics, categories, formal systems in computer science) then use abstract names. Else, just make sure it's not conflict-prone ... Graph[N,E] seems just fine to me, Graph[A,B] is also fine. Graph[Node,Edge] takes risk in conflicting with already defined types (as a Graph API user, I would be tempted to code """type Node = Container[SomeType, AnotherOne, ...]""").

All the above IMHO.

Alex

2011/11/17 Michael Schmitz <michael [at] schmitztech [dot] com>
We already have great entries in the scaladoc about type parameters.

http://www.scala-lang.org/api/current/index.html#scala.collection.Map

Peace.  Michael


2011/11/17 Daniel Sobral <dcsobral [at] gmail [dot] com>:
> 2011/11/17 √iktor Ҡlang <viktor [dot] klang [at] gmail [dot] com>:
>>
>>> > trait Graph[Node, Edge] <--- Looks great to me
>>>
>>> Except you just killed Node and Edge as trait/class names. At the very
>>> least, I'd call them ANode and AnEdge.
>>
>> trait Graph[N/*ode*/, E/*dge*/]
>
> Won't show up on Scaladoc, so what's the point? Nope, I still prefer
> ANode and AnEdge. :-)
>
> --
> Daniel C. Sobral
>
> I travel to the future all the time.
>



--
Dr Matthew PocockIntegrative Bioinformatics Group, School of Computing Science, Newcastle University mailto: turingatemyhamster [at] gmail [dot] com gchat: turingatemyhamster [at] gmail [dot] commsn: matthew_pocock [at] yahoo [dot] co [dot] uk irc.freenode.net: drdozerskype: matthew.pococktel: (0191) 2566550mob: +447535664143



--
Alex REPAIN
ENSEIRB-MATMECA - student
TECHNICOLOR R&D - intern
BORDEAUX I      - master's student
SCALA           - enthusiast


ichoran
Joined: 2009-08-14,
User offline. Last seen 2 years 3 weeks ago.
Re: Time to encourage meaningful type parameter names? Discuss
On Thu, Nov 17, 2011 at 7:56 AM, Matthew Pocock <turingatemyhamster [at] gmail [dot] com> wrote:
On 17 November 2011 12:11, Tony Morris <tonymorris [at] gmail [dot] com> wrote:
>
It is extremely important to pick meaningless names. The moment you
project meaning is the moment you start making all those mistakes that
we so often see.

Many times the types are not devoid of meaning. Consider:
trait Graph[A, B]

Bad.  Now I have to remember whether your graphs have nodes first or edges first.  I don't want to have to do that.
 
trait Graph[N, E]

Good!  Now I don't have to remember!
 
trait Graph[Node, Edge]

Why all the extra letters?  I already knew everything I needed to know.
 
trait Graph[TheNodeType, TheEdgeType]

This is just mean.

Actually, these are all bad.  Shouldn't it be

trait Graph[N <: Node, E <: Edge]

where Node and Edge are some traits that define the minimal possible interface required for something to be considered a node or an edge?  Maybe even

trait Graph[N <: Node, E <: Edge[N]]

depending on the edge interface?

Now we can see why Graph[Node, Edge] is the wrong choice.  You have labeled the types with _what you want_ without specifying that _they must be what you want_.  The more you insist with your names that you will in fact put the correct thing in that slot, the less likely you are to make the compiler insist on your behalf, and therefore the more burden you are taking upon yourself.

This is why I think the sweet spot is [N,E].  You want _some_ mnemonic because you want to know for yourself (as well as the compiler knowing) that nodes come before edges.  But [Node, Edge] is deceptive, and also steals the name Node and Edge away from what you probably really want (which are Node and Edge traits or classes).

  --Rex

d_m
Joined: 2010-11-11,
User offline. Last seen 35 weeks 2 days ago.
Re: Re: Time to encourage meaningful type parameter names? Dis

On Thu, Nov 17, 2011 at 01:45:56PM -0500, Rex Kerr wrote:
> This is why I think the sweet spot is [N,E]. You want _some_ mnemonic
> because you want to know for yourself (as well as the compiler knowing)
> that nodes come before edges. But [Node, Edge] is deceptive, and also
> steals the name Node and Edge away from what you probably really want
> (which are Node and Edge traits or classes).

Agreed.

I find the single letter convention actually makes the use of generics
more obvious to me and easier to reason about. If I had to figure out
whether everything that looked like "Node" was a type parameter or a
concrete type I would be sad. [1]

Seth Tisue
Joined: 2008-12-16,
User offline. Last seen 34 weeks 3 days ago.
Re: Re: Time to encourage meaningful type parameter names? Dis

On Thu, Nov 17, 2011 at 1:45 PM, Rex Kerr wrote:
> This is why I think the sweet spot is [N,E].  You want _some_ mnemonic
> because you want to know for yourself (as well as the compiler knowing) that
> nodes come before edges.  But [Node, Edge] is deceptive, and also steals the
> name Node and Edge away from what you probably really want (which are Node
> and Edge traits or classes).

+1

H-star Development
Joined: 2010-04-14,
User offline. Last seen 2 years 26 weeks ago.
Re: Re: Time to encourage meaningful type parameter names? Dis
i have almost never seen a case where a single letter or letter + number wasn't enough. if you use a class with type parameters, you use actual types. if you are inside the class having the class parameters, you have to take a deeper look anyway or are the author and should know enough already. taking a quick glance at the declaration won't slow you down.

Am 17.11.2011 19:45, schrieb Rex Kerr:
XXOWENR7hwgREM_0xA [at] mail [dot] gmail [dot] com" type="cite"> On Thu, Nov 17, 2011 at 7:56 AM, Matthew Pocock <turingatemyhamster [at] gmail [dot] com" rel="nofollow">turingatemyhamster [at] gmail [dot] com> wrote:
On 17 November 2011 12:11, Tony Morris <tonymorris [at] gmail [dot] com" target="_blank" rel="nofollow">tonymorris [at] gmail [dot] com> wrote:
>
It is extremely important to pick meaningless names. The moment you
project meaning is the moment you start making all those mistakes that
we so often see.

Many times the types are not devoid of meaning. Consider:
trait Graph[A, B]

Bad.  Now I have to remember whether your graphs have nodes first or edges first.  I don't want to have to do that.
 
trait Graph[N, E]

Good!  Now I don't have to remember!
 
trait Graph[Node, Edge]

Why all the extra letters?  I already knew everything I needed to know.
 
trait Graph[TheNodeType, TheEdgeType]

This is just mean.

Actually, these are all bad.  Shouldn't it be

trait Graph[N <: Node, E <: Edge]

where Node and Edge are some traits that define the minimal possible interface required for something to be considered a node or an edge?  Maybe even

trait Graph[N <: Node, E <: Edge[N]]

depending on the edge interface?

Now we can see why Graph[Node, Edge] is the wrong choice.  You have labeled the types with _what you want_ without specifying that _they must be what you want_.  The more you insist with your names that you will in fact put the correct thing in that slot, the less likely you are to make the compiler insist on your behalf, and therefore the more burden you are taking upon yourself.

This is why I think the sweet spot is [N,E].  You want _some_ mnemonic because you want to know for yourself (as well as the compiler knowing) that nodes come before edges.  But [Node, Edge] is deceptive, and also steals the name Node and Edge away from what you probably really want (which are Node and Edge traits or classes).

  --Rex


Michael Schmitz
Joined: 2011-11-01,
User offline. Last seen 42 years 45 weeks ago.
Re: Re: Time to encourage meaningful type parameter names? Dis

+1

On Thu, Nov 17, 2011 at 11:01 AM, Erik Osheim wrote:
> On Thu, Nov 17, 2011 at 01:45:56PM -0500, Rex Kerr wrote:
>> This is why I think the sweet spot is [N,E].  You want _some_ mnemonic
>> because you want to know for yourself (as well as the compiler knowing)
>> that nodes come before edges.  But [Node, Edge] is deceptive, and also
>> steals the name Node and Edge away from what you probably really want
>> (which are Node and Edge traits or classes).
>
> Agreed.
>
> I find the single letter convention actually makes the use of generics
> more obvious to me and easier to reason about. If I had to figure out
> whether everything that looked like "Node" was a type parameter or a
> concrete type I would be sad. [1]
>

Tony Morris
Joined: 2008-12-19,
User offline. Last seen 30 weeks 4 days ago.
Re: Time to encourage meaningful type parameter names? Discuss

Write a few of your graph operations. Use the type parameters as if they were nodes or edges. Notice how you can't. The proposal is akin to projecting meaning onto universally quantified variables of a logical proposition. We say, paraphrased:

For all c such that c is an element of the set Cars...

Notice how we call the variable c, not car or any other particular meaning. Doing so would degrade readability to the extent that it may distract from the fact that this variable should contain no further context than its existence. The constraint of set membership is simply an application to an operation, no different to a list sort operation requiring ordering on its elements.

It is extremely important that type variable names contain no context (that is, call it what you want but I won't be projecting an imaginary context onto it). I am only motivated to point this out because one day someone is going to bring this point up IRL and I am going to have to deal with it. I don't want to; this elusive insight that I am apparently missing according to "the naming guys" is repeatedly shown to be a failed thesis and now it is crawling into the least welcome of places (type variables).

Please modify the thesis for practical purposes.

On Nov 17, 2011 11:58 PM, "Matthew Pocock" <turingatemyhamster [at] gmail [dot] com> wrote:
[I'm now subscribed to scala-debate - sorry if you got this twice]
On 17 November 2011 13:13, Tony Morris <tonymorris [at] gmail [dot] com> wrote:
On 17/11/11 22:56, Matthew Pocock wrote:
> trait Graph[TheNodeType, TheEdgeType]

This is exactly the mistake I refer to. Now define your operations on
the data type. What do those operations (the important bits) say about
nodes and edges?

There is no meaningful isomorphism that I can repeatedly apply to Graph[Node, Edge] to get a Graph[Edge, Node] and then apply again to get back to the original graph. The nodes and edges play distinct roles. Naming them after these roles is useful documentation for the user.  
Exactly, nothing, nothing at all

It tells me a great deal about the graph API. It doesn't tell me anything about the specific choices of concrete types for Node/Edge, but that is not what type parameter names are for. It tells me what role they play in the graph, which is what type parameter names are for.  
Simon Ochsenreither
Joined: 2011-07-17,
User offline. Last seen 42 years 45 weeks ago.
Re: Re: Time to encourage meaningful type parameter names? Dis
D seems to prefix an ! to mark the difference between a type variable and a concrete type.
Matthew Pocock 3
Joined: 2010-07-30,
User offline. Last seen 42 years 45 weeks ago.
Re: Time to encourage meaningful type parameter names? Discuss
Tony,
For normal programmers, names matter. Most people don't think in lambda calculus or category theory or first order predicate logic. These people need informative names.
Matthew

On 17 November 2011 19:42, Tony Morris <tmorris [at] tmorris [dot] net> wrote:

Write a few of your graph operations. Use the type parameters as if they were nodes or edges. Notice how you can't. The proposal is akin to projecting meaning onto universally quantified variables of a logical proposition. We say, paraphrased:

For all c such that c is an element of the set Cars...

Notice how we call the variable c, not car or any other particular meaning. Doing so would degrade readability to the extent that it may distract from the fact that this variable should contain no further context than its existence. The constraint of set membership is simply an application to an operation, no different to a list sort operation requiring ordering on its elements.

It is extremely important that type variable names contain no context (that is, call it what you want but I won't be projecting an imaginary context onto it). I am only motivated to point this out because one day someone is going to bring this point up IRL and I am going to have to deal with it. I don't want to; this elusive insight that I am apparently missing according to "the naming guys" is repeatedly shown to be a failed thesis and now it is crawling into the least welcome of places (type variables).

Please modify the thesis for practical purposes.

On Nov 17, 2011 11:58 PM, "Matthew Pocock" <turingatemyhamster [at] gmail [dot] com> wrote:
[I'm now subscribed to scala-debate - sorry if you got this twice]
On 17 November 2011 13:13, Tony Morris <tonymorris [at] gmail [dot] com> wrote:
On 17/11/11 22:56, Matthew Pocock wrote:
> trait Graph[TheNodeType, TheEdgeType]

This is exactly the mistake I refer to. Now define your operations on
the data type. What do those operations (the important bits) say about
nodes and edges?

There is no meaningful isomorphism that I can repeatedly apply to Graph[Node, Edge] to get a Graph[Edge, Node] and then apply again to get back to the original graph. The nodes and edges play distinct roles. Naming them after these roles is useful documentation for the user.  
Exactly, nothing, nothing at all

It tells me a great deal about the graph API. It doesn't tell me anything about the specific choices of concrete types for Node/Edge, but that is not what type parameter names are for. It tells me what role they play in the graph, which is what type parameter names are for.  
Tony Morris 2
Joined: 2009-03-20,
User offline. Last seen 42 years 45 weeks ago.
Re: Re: Time to encourage meaningful type parameter names? Dis

Are you seriously expecting me to buy this? That I, and others who
aspire to get practical work done, are not "normal programmers", while
you, and your buddies are? Is this how you justify your thesis to
yourself? Sorry, but it's pretty transparent to me.

Do you not think I have worked with people who were once "naming guys"?
They are wrong, so they tried every trick they had, like you are doing.
They're not "naming guys" anymore.

Either demonstrate the point (an appeal to normality/abnormality
exclusion is fallacious -- surely this is obvious) or work out that
you're making a mistake with adverse practical implications. All you've
got to do is use your Node/Edge type variables as if they were nodes or
edges. Let me know when you have achieved this.

On 18/11/11 05:50, Matthew Pocock wrote:
> Tony,
>
> For normal programmers, names matter. Most people don't think in lambda
> calculus or category theory or first order predicate logic. These people
> need informative names.
>
> Matthew
>
> On 17 November 2011 19:42, Tony Morris wrote:
>
>> Write a few of your graph operations. Use the type parameters as if they
>> were nodes or edges. Notice how you can't. The proposal is akin to
>> projecting meaning onto universally quantified variables of a logical
>> proposition. We say, paraphrased:
>>
>> For all c such that c is an element of the set Cars...
>>
>> Notice how we call the variable c, not car or any other particular
>> meaning. Doing so would degrade readability to the extent that it may
>> distract from the fact that this variable should contain no further context
>> than its existence. The constraint of set membership is simply an
>> application to an operation, no different to a list sort operation
>> requiring ordering on its elements.
>>
>> It is extremely important that type variable names contain no context
>> (that is, call it what you want but I won't be projecting an imaginary
>> context onto it). I am only motivated to point this out because one day
>> someone is going to bring this point up IRL and I am going to have to deal
>> with it. I don't want to; this elusive insight that I am apparently missing
>> according to "the naming guys" is repeatedly shown to be a failed thesis
>> and now it is crawling into the least welcome of places (type variables).
>>
>> Please modify the thesis for practical purposes.
>> On Nov 17, 2011 11:58 PM, "Matthew Pocock"
>> wrote:
>>
>>> [I'm now subscribed to scala-debate - sorry if you got this twice]
>>>
>>> On 17 November 2011 13:13, Tony Morris wrote:
>>>
>>>> On 17/11/11 22:56, Matthew Pocock wrote:
>>>>> trait Graph[TheNodeType, TheEdgeType]
>>>> This is exactly the mistake I refer to. Now define your operations on
>>>> the data type. What do those operations (the important bits) say about
>>>> nodes and edges?
>>>>
>>> There is no meaningful isomorphism that I can repeatedly apply to
>>> Graph[Node, Edge] to get a Graph[Edge, Node] and then apply again to get
>>> back to the original graph. The nodes and edges play distinct roles. Naming
>>> them after these roles is useful documentation for the user.
>>>
>>>
>>>> Exactly, nothing, nothing at all
>>>
>>> It tells me a great deal about the graph API. It doesn't tell me anything
>>> about the specific choices of concrete types for Node/Edge, but that is not
>>> what type parameter names are for. It tells me what role they play in the
>>> graph, which is what type parameter names are for.
>>>
>>>
>>>> -- now you're stuck in
>>>> a cognitive quagmire. Please allow me to politely decline your
>>>> invitation.
>>>>
>>> No, now I have a documented type, using nomenclature that people are used
>>> to, where people don't have to constantly look in 2 or 3 places to figure
>>> out if A or B is the type that represents an edge or if it is the type that
>>> represents a node. Most people are not compilers and find it easier if
>>> definitions can be understood with the minimum of needing to correlate
>>> terms with other definitions.
>>>
>>> Honestly, I'm not getting what 'cognitive quagmire' I can fall into by
>>> calling the type in my graph that is being used for nodes Node rather than
>>> naming it A. It's a graph of nodes linked by edges ffs! We should be
>>> calling the node type Node and the edge type Edge. Anything else
>>> is obfuscation.
>>>
>>> Matthew
>>>
>>>
>>>> --
>>>> Tony Morris
>>>> http://tmorris.net/
>>>>
>>>>
>>>>
>>>
>>> --
>>> Dr Matthew Pocock
>>> Integrative Bioinformatics Group, School of Computing Science, Newcastle
>>> University
>>> mailto: turingatemyhamster [at] gmail [dot] com
>>> gchat: turingatemyhamster [at] gmail [dot] com
>>> msn: matthew_pocock [at] yahoo [dot] co [dot] uk
>>> irc.freenode.net: drdozer
>>> skype: matthew.pocock
>>> tel: (0191) 2566550
>>> mob: +447535664143
>>>
>>>
>

Matthew Pocock 3
Joined: 2010-07-30,
User offline. Last seen 42 years 45 weeks ago.
Re: Re: Time to encourage meaningful type parameter names? Dis


On 17 November 2011 18:34, Alex Repain <alex [dot] repain [at] gmail [dot] com> wrote:


2011/11/17 Matthew Pocock <turingatemyhamster [at] gmail [dot] com>
Yes.... Wouldn't Map[K, V] or Map[Key, Value] be more self-explanatory? Peace.


There will always be people to not catch [K,V] as [Key, Value], and others to not catch what is Key or Value because they just don't know what a Map is (let's say the hereby example is easier than the general case).

The Map data structure is intrinsically associated with the concept of a data structure that represents some key instances drawn from a key set conforming to a Key type that 'map to' some value instances drawn from a value set/bag conforming to a Value type. If a person doesn't understand Key/Value (or K/V) because they don't know what a Map is, then they need to find out what a Map is. The issue you're raising in this case isn't with the naming of the type parameters, but that the entire concept modelled by the Map isn't known to the user. Once they understand the Map abstraction, it's much easer for a normal programmer to look at signatures with the type parameters Key/Value (or K/V) than A/B and associate this back to the Map abstraction. Normal people find names and mnemonics easier to remember than random letters. We can find any amount of published literature that demonstrates this experimentally, and probably also papers that specifically dissect out what sub-population this doesn't hold for (hint - this sub-population is not over-represented in that which is also your average programmer, certainly not to the point that you can discard using informative names in APIs aimed at average programmers).
Matthew 

All the above IMHO.

Alex

2011/11/17 Michael Schmitz <michael [at] schmitztech [dot] com>
We already have great entries in the scaladoc about type parameters.

http://www.scala-lang.org/api/current/index.html#scala.collection.Map

Peace.  Michael


2011/11/17 Daniel Sobral <dcsobral [at] gmail [dot] com>:
> 2011/11/17 √iktor Ҡlang <viktor [dot] klang [at] gmail [dot] com>:
>>
>>> > trait Graph[Node, Edge] <--- Looks great to me
>>>
>>> Except you just killed Node and Edge as trait/class names. At the very
>>> least, I'd call them ANode and AnEdge.
>>
>> trait Graph[N/*ode*/, E/*dge*/]
>
> Won't show up on Scaladoc, so what's the point? Nope, I still prefer
> ANode and AnEdge. :-)
>
> --
> Daniel C. Sobral
>
> I travel to the future all the time.
>



--
Dr Matthew PocockIntegrative Bioinformatics Group, School of Computing Science, Newcastle University mailto: turingatemyhamster [at] gmail [dot] com gchat: turingatemyhamster [at] gmail [dot] commsn: matthew_pocock [at] yahoo [dot] co [dot] uk irc.freenode.net: drdozerskype: matthew.pococktel: (0191) 2566550mob: +447535664143



--
Alex REPAIN
ENSEIRB-MATMECA - student
TECHNICOLOR R&D - intern
BORDEAUX I      - master's student
SCALA           - enthusiast





--
Dr Matthew PocockIntegrative Bioinformatics Group, School of Computing Science, Newcastle Universitymailto: turingatemyhamster [at] gmail [dot] com gchat: turingatemyhamster [at] gmail [dot] commsn: matthew_pocock [at] yahoo [dot] co [dot] uk irc.freenode.net: drdozerskype: matthew.pococktel: (0191) 2566550mob: +447535664143

Copyright © 2012 École Polytechnique Fédérale de Lausanne (EPFL), Lausanne, Switzerland