title: Scala: when to use explicit type annotations
body: <p>I've been reading a lot of other people's Scala code recently, and one of the things that I have  difficultly with (coming from Java) is a lack of explicit type annotations.</p>
  
  <p>It's certainly convenient when writing code to be able to leave out type annotations -- however when reading code I often find that explicit type annotations help me to understand at a glance what code is doing more easily.</p>
  
  <p>The Scala style guide (<a href="http://docs.scala-lang.org/style/types.html" rel="nofollow">http://docs.scala-lang.org/style/types.html</a>) doesn't seem to provide any definitive guidance on this, stating:</p>
  
  <blockquote>
    <p>Use type inference where possible, but put clarity first, and favour explicitness in public APIs.</p>
  </blockquote>
  
  <p>To my mind, this is a bit contradictory. While it's clearly obvious what type this variable is:</p>
  
  <pre><code>val tokens = new HashMap[String, Int]
  </code></pre>
  
  <p>It's not so obvious what type this one is:</p>
  
  <pre><code>val tokens = readTokens()
  </code></pre>
  
  <p>So, if I was putting clarity first I would probably annotate all variables where the type is not already declared on the same line.</p>
  
  <p>Do any Scala practitioners have guidance on this? Am I crazy to be considering adding type annotations to my local variables? I'm particularly interested in hearing from folks who spend a lot of time reading scala code (for example, in code reviews), as well as writing it.</p>