Hi all,
I’m here via scala/scala.github.com issue #550 where I suggested changes to the style guide should be more widely published, specifically regarding the moving of the indentation column in scaladoc examples.
Seth’s response was that there are so many minor changes that are significant to someone that such a suggestion isn’t practical. I totally agree! And my suggestion was not very actionable. I don’t think there’s a general problem about publicising minor changes. (Also while I’m here, @som-snytt and @SethTisue , hi, you do wonderful work that I deeply appreciate).
Where I’d disagree: I think that the impact of style guide changes like this has been significantly underestimated. Scaladoc indentation is exactly the kind of thing that’s too minor to care much about so we simply defer to the “official” standpoint, as do our tools and style guides. Scala’s such a wonderfully rich language, when people write it together they need to agree a common style and do so on a solid foundation, I really doubt this is only true for me.
Also—though it’s regretful—adding “we have no official scaladoc indentation recommendation” is not going to discourage anyone when there’s one style in use in the examples and the page is the first google hit for “standard scaladoc indentation” and any number of variants, especially when it’s at scala-lang.org. People treated the old way as the standard.
Here’s what I mean:
-
emacs scala-mode - “Scaladoc comments are indented according to the Scaladoc style guide”.
-
vim-scala refers to “the indentation standard as recommended for Scaladoc comments” and links to the guide.
-
Intellij apparently uses “formatting for ScalaDoc2” in its UI.
-
scalafmt has two options for indenting scaladoc: “ScalaDoc” and “JavaDoc”.
In addition Twitter, Databricks and Spark style guides all refer to “ScalaDoc style”, as does my employer’s. Others don’t mention it specifically but begin their guides “where unspecified, refer to the official guide”. Oops, which one?
[edited to add links]
As far as I can tell no one has noticed in over six months, but each of the above is now wrong. This is confusing to those asking for the first time, “how should I format my scaladoc”? That’s how I found out today, when a colleague asked which of two options to use, and the document I referred them to had quietly switched from one to the other.
I’m sorry to say the immediate suggestion was not to add a quick snippet to our style guide to explain exactly what was meant. Instead it was to open new discussions on which style we wanted to adopt officially, someone started a slack poll and everyone cracked open their favourite can of bike shed paint. This is exactly why it was great to be able to say “I know it’s ugly but we just use The Standard Way, please add this linter config to your project and move on”.
I’m no closer to providing a concrete suggestion, but maybe I can find out if this seems like a problem to anyone else, and if so, how future problems might be mitigated? Maybe the style guide could be versioned to avoid reference rot? Or we could update the doc to write out each competing style and give them all a name? I can certainly do that.
I’m not suggesting the PR is reverted and I’d prefer not to discuss everyone’s favourite indentation style. I’m happy to create PRs for the tools I use if someone does want to make the new way the Official Scala Way, or give the options names that are better than “JavaDoc” and “ScalaDoc”.
I super-duper don’t care how scaladoc is indented, to be honest, but when someone does care, I would like to be able to point at a standard that is a) official and b) unlikely to quietly change again.