Proposed Style Guide

dot/no-dot. I find myself alternating at the moment, but I've mostly
settled on using ".", and here's why:

names map { _.toUpperCase } foldLeft("") { _ + _}

looks reasonable, but won't compile. Nor will

names map { _.toUpperCase }.foldLeft("") { _ + _}

After running into this compile error (the latter version has a really
arcane error message!) countless times, I've decided the easiest way
to avoid it (besides always using reduceLeft) is to just use ".".

I use the following:

(names map { _.toUpperCase }).foldLeft("") { _ + _ }

Either that, or I'll split it across multiple lines.  It's a bit annoying, but it fortunately does not come up too often.

Daniel

Hi Daniel. Thanks for undertaking this effort.

> Very true. However, this treats parentheses like braces. I would
> rather keep the rules for this distinct. I usually treat
> parentheses like Lisp parens (with the closing paren on the same
> line as the last expression) and braces like Java-style braces.
> This emphasizes the grammatical differences between the two.

If we’re taking votes, I much prefer treating parentheses like braces.
This applies in three situations:

1. Line wrapping, as with:

val result = (
1 + 2 + 3 + 4 + 5 + 6 +
7 + 8 + 9 + 10 + 11 + 12 + 13 + 14 +
15 + 16 + 17 + 18 + 19 + 20
)

2. Methods with numerous arguments:

val myOnerousAndLongFieldNameWithNoRealPoint = foo(
someVeryLongFieldName,
andAnotherVeryLongFieldName,
"this is a string”,
3.1415
)

3. Foreach comprehensions

I honestly prefer the "syntactically-confusing" } { construct — i see
no reason to change the entire structure of the for-comprehension just
because it will end with a side-effect instead of a yield — but one
could also do:

for (
x <- board.rows;
y <- board.files
) {
printf("(%d, %d)", x, y)
}

Two cents deposited. Perhaps we can do a little survey on some of
these more controversial bits :)

cheers,
~aaron

Hi Daniel,

On Sun, 2009-11-15 at 15:57 -0600, Daniel Spiewak wrote:
> I haven't done a formal survey, but I can say that the majority of
> Scala code does seem to use the [A, B] convention. As you said, the
> new collections library does not use this convention (though the old
> one does). However, as I mentioned earlier, I'm using the standard
> library as a general hint toward "correct" style, but I'm actually
> giving it even less weight than one-off libraries by prominent
> community members.

No-one is as prominent as Martin, I would say.

> It's hard to keep a consistent style across a library as large as
> Scala's. However, individual coders can be consistent. Furthermore,
> most of the Scala standard lib was developed before the community
> conventions evolved.

This doesn't apply to the new collections library. It has been developed
mostly by Martin and Adriaan as far as I can tell, it has been developed
recently, it uses type parameters a lot and some thought went into the
type parameter names. In other words, worth paying attention to.

> I would be willing to go with [K, V] instead of [A, B] (as I said, I
> do prefer that style). However, this doesn't work in every case. In
> Java, one almost never defines a type with more than two type
> parameters. In Scala, that sort of thing is commonplace. While [K,
> V] may be more readable for something like Map or List, but it fails
> to scale beyond two or three parameters. That was the proverbial
> straw that broke the camel's back, at least it was for me. I prefer
> consistent style which scales across all cases.

If one takes that reasoning to an extreme, we should label values and
variables a, b, c too. :)

Best,
Ismael

 

** Unit/Void methods

I see no gains to

 def voidMethod() { /* do something */ }

over

 def voidMethod(): Unit = { /* do something */ }

The advantage boils down to the fact that it is not required to explicitly annotate the : Unit type.  Of course, we can always rely on type inference to get the type for us, but such a technique very seldom works with unit methods.  This is because non-trivial unit methods will most often consist of an expression which does not return Unit.  Thus, the public signature of the method could be wrong, and you would never catch it.  This ties back into the advice to explicitly annotate all public methods.  If we use the short-hand Unit syntax, we can get the explicit annotation without extra syntax.  In fact, it actually saves us two characters over the inferred form (for whatever that's worth).  

I see what you mean, though I'm still not totally sold on this; I think it's all about the equals sign; it just seems like a weird shortcut syntax, almost as if it's a mistake to allow it.  But, I suppose it might look weird to use inferencing everywhere EXCEPT Unit methods, so I'm not sure that makes it any better.
 

** Paren-less vs 0-arg functions/method

I found this confusing.  I think the paren-less form should be reserved for DSLs
only and one should always use parens.  It just makes things a LOT clearer;
when you see parens, you are seeing a function/method call.

This is a very important one.  I can't emphasize this idiom enough.  The paren-less form is important because it unifies the signature of side-effect-free methods with actual fields.  Thus, it is possible to switch between def, val and lazy val

without changing the public interface.  Finally, strict adherence to the syntax makes it easy to see which methods have side-effects and which ones are functional.

I'm sold based on your explanation, I think perhaps the text could use some tightening up, because I do agree that interchanging def and val is an important advantage to the syntax.
 
Dave

I think it might be a good idea to look into using sphinx
(http://sphinx.pocoo.org) to organize the document. It is a
documentation generation system built around reStructuredText. It adds
the ability to join a hierarchy of source files to one master document,
pulling table of contents entries from each one. The master document can
be split into a multi-page version for viewing on the web with links for
next/previous/parent sections. It also includes code syntax highlighting
using pygments and adds some additional markup constructs for
cross-references, code listings, etc. I'm going to take a stab at
getting it set up and push it to a github fork if I'm successful.

Nifty!  I didn't even know this existed.  I'm definitely in favor.
Daniel

On Sun, Nov 15, 2009 at 6:22 PM, Geoff Reedy <geoff@programmer-monk.net> wrote:

I think it might be a good idea to look into using sphinx
(http://sphinx.pocoo.org) to organize the document. It is a
documentation generation system built around reStructuredText. It adds
the ability to join a hierarchy of source files to one master document,
pulling table of contents entries from each one. The master document can
be split into a multi-page version for viewing on the web with links for
next/previous/parent sections. It also includes code syntax highlighting
using pygments and adds some additional markup constructs for
cross-references, code listings, etc. I'm going to take a stab at
getting it set up and push it to a github fork if I'm successful.

I apologise for making a fuss over something so trivial, but I really have to
object to the underscore naming convention for private property variables,
for the same reasons given in the guide itself.

Underscores have 5 odd different overloaded meanings in Scala, most of which
are very important and common. Names which choose to use underscores are
therefore extremely "noisy", and require many more brain cycles to scan.
For such a common use case, almost any naming convention I can think of
would be preferable to using an underscore. Why make an exception here to
the "heavy" discouragement?

I myself use
private var fooVar = 1
def foo = fooVar
def foo_=(f:Int) = fooVar = f

It's a bit ugly, but really, any convention at all would be better than
underscores.

Anyway sorry for getting all religious, these debates always tend to
generate more heat than light ;)
Ken

Daniel Spiewak wrote:
>
> In "Inference", "Just for the sake of safety, you should annotate
> all public methods in your class." This should be stronger since
> code is read more than it is written. Anything longer than a single
> line or two must be annotated with the return type in our code. In
> my mind, almost the methods in the document should be annotated with
> a return type to make it clear that it is a requirement.
>
>
> Sometimes, yes. However, on many occaisions, I have found that
> annotating methods actually reduces readability. In general, the case
> should dictate the style. However, that's kinda hard to put in a
> guide. :-) I figure that people will annotate more or less with common
> sense and it's really only in signature-affecting members that it
> becomes a serious issue.

It's not just readability, it's the time to figure out what it returns. I work
in emacs, so I don't get type annotations that other GUIs provide. It's always
faster just to see what it returns than the parse the method body to figure it out.

> "Void" Methods. We don't permit them in our code, we require the
> ":Unit = {" style. It's too easy to try to write a short method
> with no type annotation and forget the = and now the method returns
> Unit. There was a debate whether to remote this from the language,
> so it's use throughout the community isn't 100%.
>
>
> Honestly, how often do you /change/ a void method to one which returns a
> real value? I actually can't recall ever doing that (not just in Scala,
> but in Java or any other language). There's no need to optimize for a
> case which is so incredibly rare.

I'm not saying changing the method signature. I'm saying that forgetting the =
gets you a void method. And for consistency, it's easier just to have methods
always be written without the =.

> "Higher-Order Functions" we use
>
> names.map(_.toUpperCase).filter(_.length > 5)
>
>
> As mentioned earlier, I disagree pretty strongly with this syntax. I
> have two main reasons. First, map, filter and friends are logically
> just operators, so they belong in the infix position. Second, I really
> believe that function values should always be delimited with curly
> braces. This makes it visually explicit that the block in question is
> "not like the others". It allows the prospective code reader to skim
> the line very quickly and immediately see that there are two function
> values /without/ having to parse their contents. With your style, the
> reader must visually "drill into" the contents of each parameter,
> looking for an underscore. This gets very tiring, particularly on more
> complex expressions.

I don't really view them as operators but just as methods. I find the fewer {
and }'s less busy on my eye than having ( )'s.

One could always have

names.map( { _.toUpperCase } ).filter( { _.length > 5 } )

but that's the worst of both worlds. Also, I look more at the operators/method
names than at the bodies and know that map filter take a function value.

I guess we'll need to disagree.

> In "Multi-Unit Files" I'm pretty sure this will cause ant to
> recompile the source file every time because there is no exact match
> on the generates class file and the source file. My compiles are
> already too long as it is, so I don't want to compile files I don't
> need to.
>
>
> No, not really. Maybe re-parse, but that has to happen anyway. As far
> as I know, the Scala compiler attaches no significance to the name of
> the .scala file.

Actually, the ant scalac task does take the *.scala filename and look for a
corresponding *.class file. If it finds the *.class file that is newer than the
*.scala then it does recompile. If it doesn't find a *.class file then it will
recompile.

For example:

$ git clone git://github.com/blair/configgy.git
$ cd configgy
$ ant compile-tests

Run "ant compile-tests" again and it won't recompile anything.

Now rename a file.

$ mv src/main/scala/net/lag/configgy/Importer.scala
src/main/scala/net/lag/configgy/i.scala

Now run "ant compile-tests" again. Each time you run it it'll recompile that
file and generate new classes. you can see this with

$ find -name \*.class -ls | sort > 1
$ ant compile-tests
$ find -name \*.class -ls | sort > 2
$ ant compile-tests
$ diff 1 2

Only the files from importer.scala are recompiled.

If you do want a lower case scala file, then it should contain an empty private
class with the same name to prevent compilation.

On my older Linux box if I a matching Scala source file with a class file then
"ant compile-tests" takes 4.01 seconds, if there's a mismatch then it takes 9.3
seconds.

Regards,
Blair

So I've pushed a sphinx version of the document to github. You can see
the results at http://greedy.github.com/scala-style/

The source is at http://github.com/greedy/scala-style/tree/sphinx

In my opinion it looks really nice.

To build the documentation from the source you need the sphinx and
github-tools python modules installed. They should both be
easy_install-able. Then just run make html or make pdf. Additional
targets are available with make help.

We might want to flatten the document heirarchy somewhat since some of
the pages end up with nearly nothing in them.

For what it's worth, in retrospect I believe the def foo { ... }
syntax was a mistake. I introduced it (against the recommendations of
several others) in order to make Scala easier on the eyes of Java
programmers. I did not want to explain about Unit immediately when I
introduced Scala by means of a trivial hello world like program.

But unfortunately, the new syntax has introduced an uneasy choice,
where it is not always clear what is better. For instance,

def foo {
println(x)
}

is shorter than the : Unit = alternative. But

def foo(x: C) {
x match {
...
}
}

and

def foo() { delegate.foo() }

are longer (at least in LOC) than their alternatives:

def foo(x: C): Unit = x match {
...
}

def foo(): Unit = delegate.foo()

Also, the = form is often shorter when the : Unit result is intended
to be inferred.

Altogether, this makes it hard to give a recommendation. The purist
approach would be to always recommend the : Unit = form now,
deprecate the { ... } form later and abolish it at some point in the
future. But I'm not sure it's worth the hassle.

Cheers

> Von: martin odersky
>
> I think that's too narrow. The infix notation makes also a nice
> sentence form. For instance, if instead of
>
> actor ! msg
>
> you'd write
>
> actor send msg
>
> I think that would work just as well. Neither is a purely functional
> operator. But both are clearer than
>
> actor.send(msg)

"actor
send msg" looks good and is free from technical parts like ".()", but
it makes understanding source code harder, because there is not only
one way to write a method call. Think about why Python is so easy to
read and understand. It is so because

"There should be one-- and preferably only one --obvious way to do it."

http://www.python.org/dev/peps/pep-0020/

Some
guys are saying Scala would be the new Perl because of sometimes hard
to read/understand code. (I heard this more than once!) I really
dislike method names like "/:" (see: http://www.scala-lang.org/docu/files/api/scala/Iterable.html#%2F%3A%28B%29). "/:" is not a common symbol like "+" and thus hard to read. Look at Perl with $, @, ~, #, %,
$#, =>, $_, <$name>, =~ ... It would be much easier to read, if Perl would use natural words.

I like the infix notation for operators like in 5 + 3 but I think it would be good, to use generally the .()-notation.

Christian

That look really awesome!  A couple questions:

I know zero about python, how do I install those modules?

Where would be a good place in the document to link to meta-data such as GH repos and the LaTeX version?  (I had it in the overview, which is arguably not the best place for it)

Is there a target that pushes to gh-pages?

Out of curiosity, why would I want JSON, pickle, or qthelp files?


Dave

---
My Blog: http://www.naildrivin5.com/blog
Scala Tour for Java Developers: http://www.naildrivin5.com/scalatour
Fork me on Github: http://davetron5000.github.com



On Mon, Nov 16, 2009 at 12:49 AM, Geoff Reedy <geoff@programmer-monk.net> wrote:

So I've pushed a sphinx version of the document to github. You can see
the results at http://greedy.github.com/scala-style/

The source is at http://github.com/greedy/scala-style/tree/sphinx

In my opinion it looks really nice.

To build the documentation from the source you need the sphinx and
github-tools python modules installed. They should both be
easy_install-able. Then just run make html or make pdf. Additional
targets are available with make help.

We might want to flatten the document heirarchy somewhat since some of
the pages end up with nearly nothing in them.

On Mon, Nov 16, 2009 at 10:22:37AM -0500, David Copeland said
> That look really awesome! A couple questions:
>
> I know zero about python, how do I install those modules?

You should be able to run: easy_install sphinx github-tools

> Where would be a good place in the document to link to meta-data such as GH
> repos and the LaTeX version? (I had it in the overview, which is arguably
> not the best place for it)

Looks like there's a configuration option to add custom content to the
sidebar. I think that'd be the best place for it.

> Is there a target that pushes to gh-pages?

Not yet. I'd like to have one though. I think that the github-tools
module might have something to do it. I just have to find it and call to
it.

> Out of curiosity, why would I want JSON, pickle, or qthelp files?

I think that there is a specialized webapp that can read the JSON or
pickle files. Sphinx is also intended for API documentation so I think
that is why qthelp is an option. I didn't write the Makefile, it was
generated by the spinx-quickstart script. I did add the pdf target
though.

I'm a total sphinx newbie too. I'm sure that there's lots of room to
improve from here.

Cool, I got that working.  I think the output and org structure is superior to what I originally set up.  I'm going to merge that in to my tree at some point today.  The task I used in the Rakefile to copy stuff to gh-pages can be used standalone, I believe, so I can look into that.  Nice work!

Dave

---
My Blog: http://www.naildrivin5.com/blog
Scala Tour for Java Developers: http://www.naildrivin5.com/scalatour
Fork me on Github: http://davetron5000.github.com



On Mon, Nov 16, 2009 at 10:54 AM, Geoff Reedy <geoff@programmer-monk.net> wrote:

On Mon, Nov 16, 2009 at 10:22:37AM -0500, David Copeland said
> That look really awesome!  A couple questions:
>
> I know zero about python, how do I install those modules?

You should be able to run: easy_install sphinx github-tools

> Where would be a good place in the document to link to meta-data such as GH
> repos and the LaTeX version?  (I had it in the overview, which is arguably
> not the best place for it)

Looks like there's a configuration option to add custom content to the
sidebar. I think that'd be the best place for it.

> Is there a target that pushes to gh-pages?

Not yet. I'd like to have one though. I think that the github-tools
module might have something to do it. I just have to find it and call to
it.

> Out of curiosity, why would I want JSON, pickle, or qthelp files?

I think that there is a specialized webapp that can read the JSON or
pickle files. Sphinx is also intended for API documentation so I think
that is why qthelp is an option. I didn't write the Makefile, it was
generated by the spinx-quickstart script. I did add the pdf target
though.

I'm a total sphinx newbie too. I'm sure that there's lots of room to
improve from here.

OK, merged this all into my repo and manually updated it on Github Pages; I dig this format a lot.  I'll sort out latex/pdf this evening.

Dave

---
My Blog: http://www.naildrivin5.com/blog
Scala Tour for Java Developers: http://www.naildrivin5.com/scalatour
Fork me on Github: http://davetron5000.github.com



On Mon, Nov 16, 2009 at 11:32 AM, David Copeland <davec@naildrivin5.com> wrote:

Cool, I got that working.  I think the output and org structure is superior to what I originally set up.  I'm going to merge that in to my tree at some point today.  The task I used in the Rakefile to copy stuff to gh-pages can be used standalone, I believe, so I can look into that.  Nice work!

Dave

---
My Blog: http://www.naildrivin5.com/blog
Scala Tour for Java Developers: http://www.naildrivin5.com/scalatour
Fork me on Github: http://davetron5000.github.com



On Mon, Nov 16, 2009 at 10:54 AM, Geoff Reedy <geoff@programmer-monk.net> wrote:

On Mon, Nov 16, 2009 at 10:22:37AM -0500, David Copeland said
> That look really awesome!  A couple questions:
>
> I know zero about python, how do I install those modules?

You should be able to run: easy_install sphinx github-tools

> Where would be a good place in the document to link to meta-data such as GH
> repos and the LaTeX version?  (I had it in the overview, which is arguably
> not the best place for it)

Looks like there's a configuration option to add custom content to the
sidebar. I think that'd be the best place for it.

> Is there a target that pushes to gh-pages?

Not yet. I'd like to have one though. I think that the github-tools
module might have something to do it. I just have to find it and call to
it.

> Out of curiosity, why would I want JSON, pickle, or qthelp files?

I think that there is a specialized webapp that can read the JSON or
pickle files. Sphinx is also intended for API documentation so I think
that is why qthelp is an option. I didn't write the Makefile, it was
generated by the spinx-quickstart script. I did add the pdf target
though.

I'm a total sphinx newbie too. I'm sure that there's lots of room to
improve from here.

Daniel Spiewak wrote:
>
> One of the things about Scala which has always bugged me is the *lack* of
> an
> official style guide. There is simply no "right" way of doing things,
> syntactically speaking. Over the years, the Scala community has attempted
> to fill the void (as it were) by defining a set of unofficial,
> word-of-mouth
> conventions. Things like when to add parentheses to no-arg methods or
> what
> the preferred function literal definition style may be.
>

Hi!

I have a question which seems to be open in the guide (and in this
discussion, as far as I could follow). What is the preferred style when I
need generics for a variable definition?

val map: Map[Int, String] = Map()
--or--
val map = Map[Int, String]()

val list: List[String] = Nil
--or--
val list = List[String]()

My code contains a mix of both versions...

Cheers,
Daniel

I don't get how choosing names for type parameters is really any
different to naming anything else. Short names are preferable to long
names, and meaningful names are preferable to meaningless ones. Of
course, there's a trade-off there.

For classes with multiple type parameters with different meanings it
seems very sensible to err on the side of explicitness. I can't think
of a great example but perhaps Graph[Node, Edge] is plausible. For
classes with a single type parameter which carries no particular meaning
(e.g. the element type in collection classes) then it seems very
sensible to call it "A" rather than "Elem" or similar. (I can see both
sides for Map[K, V] vs Map[A, B]).

In either case, I really don't like the idea of using all-caps like
Foo[BAR] as has been suggested for multi-letter type parameters. We use
initial-caps for every other type, including inner classes and inner
traits. And what about abstract type members? They are so similar to
type parameters that it seems bizarre to use a different naming
convention. But if we use all-caps for abstract type members then stuff
like the following (where we make an abstract type member concrete in a
subclass) becomes much less pretty:

class Graph
{
type Node
}

class SpecialGraph
{
class Node
{
...
}
}

Thanks,

Matt

Ismael Juma wrote:
> Hi Daniel,
>
> On Sun, 2009-11-15 at 15:57 -0600, Daniel Spiewak wrote:
>> I haven't done a formal survey, but I can say that the majority of
>> Scala code does seem to use the [A, B] convention. As you said, the
>> new collections library does not use this convention (though the old
>> one does). However, as I mentioned earlier, I'm using the standard
>> library as a general hint toward "correct" style, but I'm actually
>> giving it even less weight than one-off libraries by prominent
>> community members.
>
> No-one is as prominent as Martin, I would say.
>
>> It's hard to keep a consistent style across a library as large as
>> Scala's. However, individual coders can be consistent. Furthermore,
>> most of the Scala standard lib was developed before the community
>> conventions evolved.
>
> This doesn't apply to the new collections library. It has been developed
> mostly by Martin and Adriaan as far as I can tell, it has been developed
> recently, it uses type parameters a lot and some thought went into the
> type parameter names. In other words, worth paying attention to.
>
>> I would be willing to go with [K, V] instead of [A, B] (as I said, I
>> do prefer that style). However, this doesn't work in every case. In
>> Java, one almost never defines a type with more than two type
>> parameters. In Scala, that sort of thing is commonplace. While [K,
>> V] may be more readable for something like Map or List, but it fails
>> to scale beyond two or three parameters. That was the proverbial
>> straw that broke the camel's back, at least it was for me. I prefer
>> consistent style which scales across all cases.
>
> If one takes that reasoning to an extreme, we should label values and
> variables a, b, c too. :)
>
> Best,
> Ismael
>

What makes it confusing is that the  scaladoc tool creates links to these non-existent classes that go nowhere.

It's nice to know if a class-name-looking-string I'm looking at is actually defined somewhere.  I think the all-caps thing is a very easy clue that you are looking at a type parameter and not a class/trait/object.  I mean, this code here is pretty darn confusing:

class Foo[Elem](x:Elem) {
  def get:Elem = x
}

class Elem(x:String) {
  override def toString = x
}

That being said, the 2.8 scala library does this all over the place.

Dave

---
My Blog: http://www.naildrivin5.com/blog
Scala Tour for Java Developers: http://www.naildrivin5.com/scalatour
Fork me on Github: http://davetron5000.github.com



On Sun, Nov 22, 2009 at 9:35 PM, Matt Shannon <matt.shannon@cantab.net> wrote:

I don't get how choosing names for type parameters is really any different to naming anything else.  Short names are preferable to long names, and meaningful names are preferable to meaningless ones.  Of course, there's a trade-off there.

For classes with multiple type parameters with different meanings it seems very sensible to err on the side of explicitness.  I can't think of a great example but perhaps Graph[Node, Edge] is plausible.  For classes with a single type parameter which carries no particular meaning (e.g. the element type in collection classes) then it seems very sensible to call it "A" rather than "Elem" or similar.  (I can see both sides for Map[K, V] vs Map[A, B]).

In either case, I really don't like the idea of using all-caps like Foo[BAR] as has been suggested for multi-letter type parameters.  We use initial-caps for every other type, including inner classes and inner traits.  And what about abstract type members?  They are so similar to type parameters that it seems bizarre to use a different naming convention.  But if we use all-caps for abstract type members then stuff like the following (where we make an abstract type member concrete in a subclass) becomes much less pretty:

 class Graph
 {
   type Node
 }

 class SpecialGraph
 {
   class Node
   {
     ...
   }
 }

Thanks,

Matt


Ismael Juma wrote:

Hi Daniel,

On Sun, 2009-11-15 at 15:57 -0600, Daniel Spiewak wrote:

I haven't done a formal survey, but I can say that the majority of
Scala code does seem to use the [A, B] convention.  As you said, the
new collections library does not use this convention (though the old
one does).  However, as I mentioned earlier, I'm using the standard
library as a general hint toward "correct" style, but I'm actually
giving it even less weight than one-off libraries by prominent
community members.

No-one is as prominent as Martin, I would say.

 It's hard to keep a consistent style across a library as large as
Scala's.  However, individual coders can be consistent.  Furthermore,
most of the Scala standard lib was developed before the community
conventions evolved.

This doesn't apply to the new collections library. It has been developed
mostly by Martin and Adriaan as far as I can tell, it has been developed
recently, it uses type parameters a lot and some thought went into the
type parameter names. In other words, worth paying attention to.

I would be willing to go with [K, V] instead of [A, B] (as I said, I
do prefer that style).  However, this doesn't work in every case.  In
Java, one almost never defines a type with more than two type
parameters.  In Scala, that sort of thing is commonplace.  While [K,
V] may be more readable for something like Map or List, but it fails
to scale beyond two or three parameters.  That was the proverbial
straw that broke the camel's back, at least it was for me.  I prefer
consistent style which scales across all cases.

If one takes that reasoning to an extreme, we should label values and
variables a, b, c too. :)

Best,
Ismael

I agree completely.

Instead of using all-caps (which I think looks a bit off), I tend to name the type parameter/abstract type with a "Type" suffix (where suitable) to signal its role as a type name (i.e. Graph[NodeType, EdgeType] or Function1[ParameterType, ResultType]). It is perhaps not the most concise convention (making the type name at most four characters longer than the all-caps convention), but it serves its purpose well (and looks nicer in my opinion).

Alternately, by always using an IDE which displays type such type names differently from classes/traits, the problem is avoided.

Greetings
Odd

-----Original Message-----
From: Matt Shannon [mailto:matt.shannon@cantab.net]
Sent: den 23 november 2009 03:35
To: Ismael Juma
Cc: Daniel Spiewak; Blair Zajac; scala@listes.epfl.ch
Subject: Re: [scala] Proposed Style Guide

I don't get how choosing names for type parameters is really any
different to naming anything else. Short names are preferable to long
names, and meaningful names are preferable to meaningless ones. Of
course, there's a trade-off there.

For classes with multiple type parameters with different meanings it
seems very sensible to err on the side of explicitness. I can't think
of a great example but perhaps Graph[Node, Edge] is plausible. For
classes with a single type parameter which carries no particular meaning
(e.g. the element type in collection classes) then it seems very
sensible to call it "A" rather than "Elem" or similar. (I can see both
sides for Map[K, V] vs Map[A, B]).

In either case, I really don't like the idea of using all-caps like
Foo[BAR] as has been suggested for multi-letter type parameters. We use
initial-caps for every other type, including inner classes and inner
traits. And what about abstract type members? They are so similar to
type parameters that it seems bizarre to use a different naming
convention. But if we use all-caps for abstract type members then stuff
like the following (where we make an abstract type member concrete in a
subclass) becomes much less pretty:

class Graph
{
type Node
}

class SpecialGraph
{
class Node
{
...
}
}

Thanks,

Matt

Ismael Juma wrote:
> Hi Daniel,
>
> On Sun, 2009-11-15 at 15:57 -0600, Daniel Spiewak wrote:
>> I haven't done a formal survey, but I can say that the majority of
>> Scala code does seem to use the [A, B] convention. As you said, the
>> new collections library does not use this convention (though the old
>> one does). However, as I mentioned earlier, I'm using the standard
>> library as a general hint toward "correct" style, but I'm actually
>> giving it even less weight than one-off libraries by prominent
>> community members.
>
> No-one is as prominent as Martin, I would say.
>
>> It's hard to keep a consistent style across a library as large as
>> Scala's. However, individual coders can be consistent. Furthermore,
>> most of the Scala standard lib was developed before the community
>> conventions evolved.
>
> This doesn't apply to the new collections library. It has been developed
> mostly by Martin and Adriaan as far as I can tell, it has been developed
> recently, it uses type parameters a lot and some thought went into the
> type parameter names. In other words, worth paying attention to.
>
>> I would be willing to go with [K, V] instead of [A, B] (as I said, I
>> do prefer that style). However, this doesn't work in every case. In
>> Java, one almost never defines a type with more than two type
>> parameters. In Scala, that sort of thing is commonplace. While [K,
>> V] may be more readable for something like Map or List, but it fails
>> to scale beyond two or three parameters. That was the proverbial
>> straw that broke the camel's back, at least it was for me. I prefer
>> consistent style which scales across all cases.
>
> If one takes that reasoning to an extreme, we should label values and
> variables a, b, c too. :)
>
> Best,
> Ismael
>

I like the XxxType pattern MUCH better than not.  I also think that code style should be as effective in B&W as in an IDE.

Dave

---
My Blog: http://www.naildrivin5.com/blog
Scala Tour for Java Developers: http://www.naildrivin5.com/scalatour
Fork me on Github: http://davetron5000.github.com



On Tue, Nov 24, 2009 at 7:47 AM, Odd Möller <odd.moller@traveas.com> wrote:

I agree completely.

Instead of using all-caps (which I think looks a bit off), I tend to name the type parameter/abstract type with a "Type" suffix (where suitable) to signal its role as a type name (i.e. Graph[NodeType, EdgeType] or Function1[ParameterType, ResultType]). It is perhaps not the most concise convention (making the type name at most four characters longer than the all-caps convention), but it serves its purpose well (and looks nicer in my opinion).

Alternately, by always using an IDE which displays type such type names differently from classes/traits, the problem is avoided.

Greetings
Odd


-----Original Message-----
From: Matt Shannon [mailto:matt.shannon@cantab.net]
Sent: den 23 november 2009 03:35
To: Ismael Juma
Cc: Daniel Spiewak; Blair Zajac; scala@listes.epfl.ch
Subject: Re: [scala] Proposed Style Guide

I don't get how choosing names for type parameters is really any
different to naming anything else.  Short names are preferable to long
names, and meaningful names are preferable to meaningless ones.  Of
course, there's a trade-off there.

For classes with multiple type parameters with different meanings it
seems very sensible to err on the side of explicitness.  I can't think
of a great example but perhaps Graph[Node, Edge] is plausible.  For
classes with a single type parameter which carries no particular meaning
(e.g. the element type in collection classes) then it seems very
sensible to call it "A" rather than "Elem" or similar.  (I can see both
sides for Map[K, V] vs Map[A, B]).

In either case, I really don't like the idea of using all-caps like
Foo[BAR] as has been suggested for multi-letter type parameters.  We use
initial-caps for every other type, including inner classes and inner
traits.  And what about abstract type members?  They are so similar to
type parameters that it seems bizarre to use a different naming
convention.  But if we use all-caps for abstract type members then stuff
like the following (where we make an abstract type member concrete in a
subclass) becomes much less pretty:

  class Graph
  {
    type Node
  }

  class SpecialGraph
  {
    class Node
    {
      ...
    }
  }

Thanks,

Matt


Ismael Juma wrote:
> Hi Daniel,
>
> On Sun, 2009-11-15 at 15:57 -0600, Daniel Spiewak wrote:
>> I haven't done a formal survey, but I can say that the majority of
>> Scala code does seem to use the [A, B] convention.  As you said, the
>> new collections library does not use this convention (though the old
>> one does).  However, as I mentioned earlier, I'm using the standard
>> library as a general hint toward "correct" style, but I'm actually
>> giving it even less weight than one-off libraries by prominent
>> community members.
>
> No-one is as prominent as Martin, I would say.
>
>>   It's hard to keep a consistent style across a library as large as
>> Scala's.  However, individual coders can be consistent.  Furthermore,
>> most of the Scala standard lib was developed before the community
>> conventions evolved.
>
> This doesn't apply to the new collections library. It has been developed
> mostly by Martin and Adriaan as far as I can tell, it has been developed
> recently, it uses type parameters a lot and some thought went into the
> type parameter names. In other words, worth paying attention to.
>
>> I would be willing to go with [K, V] instead of [A, B] (as I said, I
>> do prefer that style).  However, this doesn't work in every case.  In
>> Java, one almost never defines a type with more than two type
>> parameters.  In Scala, that sort of thing is commonplace.  While [K,
>> V] may be more readable for something like Map or List, but it fails
>> to scale beyond two or three parameters.  That was the proverbial
>> straw that broke the camel's back, at least it was for me.  I prefer
>> consistent style which scales across all cases.
>
> If one takes that reasoning to an extreme, we should label values and
> variables a, b, c too. :)
>
> Best,
> Ismael
>