Quiet changes to the style guide

[eddsteel]

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.

[heathermiller]

Maybe the solution is two-fold;

1. Version the style guide
2. Scalafmt/scalafix config files that are in-step with the style guide version numbers.

That is, if someone makes a change to the style guide, they’d also be required to correspondingly update scalafmt/scalafix configs (not sure this is currently even possible for all valid changes to the style guide, though it’s a strong motivation for moving towards scalafmt/scalafix as the central tool for enforcing these guidelines…) cc/ @olafurpg

[dwijnand]

I recently found out that the rust community uses RFCs for its formatting guideline changes. See https://github.com/rust-lang-nursery/fmt-rfcs

[eddsteel]

I totally agree. We do have that in our code and builds but also a lot of legacy code where it’s missing.

I think the problem here is ambiguity – you still need to write the scalafmt config file and know what “scaladoc style” means.

[olafurpg]

I was not aware the official Scaladoc guidelines had changed. The scalafmt “Scaladoc” setting matches the old style, so does the current “use scaladoc indent for leading asterisk” setting in the IntelliJ Scala plugin.

I left a comment in https://github.com/scala/scala.github.com/pull/801#pullrequestreview-44702920

I’m not convinced it’s a good idea to advertise three nuanced styles, this will only further tax tooling developers. I like the idea of versioning the style guide as proposed by @heathermiller and promoting a single style decided with an open process like the Rust fmt-rfcs (thanks for the link @dwijnand). This would at least help manage the proliferation of configuration options in scalafmt (see http://scalameta.org/scalafmt/#Other).